Référence Oracle NoSQL Database Cloud Service

Types de données pris en charge

Oracle NoSQL Database Cloud Service prend en charge les types de données les plus courants.

Type de données	Description
`BINARY`	Séquence d'aucun octet ou de plusieurs octets. La taille de stockage correspond au nombre d'octets plus un codage de la taille de la baie d'octets, qui est une variable, en fonction de la taille de la baie.
`FIXED_BINARY`	Tableau d'octets à taille fixe. Il n'y a pas de surcharge de codage supplémentaire pour ce type de données.
`BOOLEAN`	Type de données avec l'une des deux valeurs possibles : `TRUE` ou `FALSE`. La taille de stockage du booléen est de 1 octet.
`DOUBLE`	Nombre à virgule flottante long, encodé à l'aide de 8 octets de stockage pour les clés d'index. S'il s'agit d'une clé primaire, il utilise 10 octets de stockage.
`FLOAT`	Nombre à virgule flottante long, encodé à l'aide de 4 octets de stockage pour les clés d'index. S'il s'agit d'une clé primaire, il utilise 5 octets de stockage.
`LONG`	Un nombre entier long a un encodage de longueur variable qui utilise 1 à 8 octets de stockage en fonction de la valeur. S'il s'agit d'une clé primaire, il utilise 10 octets de stockage.
`INTEGER`	Un nombre entier long a un encodage de longueur variable qui utilise 1 à 4 octets de stockage en fonction de la valeur. S'il s'agit d'une clé primaire, il utilise 5 octets de stockage.
`STRING`	Séquence de zéro ou plusieurs caractères Unicode. Le type String est codé en UTF-8 et stocké dans ce codage. La taille de stockage correspond au nombre d'octets UTF-8 plus la longueur, qui peut être de 1 à 4 octets en fonction du nombre d'octets dans le codage. Lorsqu'elle est stockée dans une clé d'index, la taille de stockage correspond au nombre d'octets UTF-8 plus un seul octet de terminaison NULL.
`NUMBER`	Nombre décimal signé à précision arbitraire. Il est sérialisé dans un format de tableau d'octets qui peut être utilisé pour les comparaisons ordonnées. Le format comporte 2 parties : Signe et exposant plus un seul chiffre. Cela prend entre 1 et 6 octets, mais normalement 2 sauf si l'exposant est assez grand La mantisse de la valeur qui est d'environ un octet pour 2 chiffres Exemples : 12.345678 sérialise en 6 octets 1.234E+102 sérialise en 5 octets Remarques : Lorsque vous devez utiliser des valeurs numériques dans votre schéma, il est recommandé de choisir les types de données dans l'ordre indiqué ci-dessous : INTEGER, LONG, FLOAT, DOUBLE, NUMBER Evitez NUMBER sauf si vous en avez vraiment besoin pour votre cas d'utilisation car NUMBER est coûteux en termes de stockage et de puissance de traitement.
`TIMESTAMP`	Point dans le temps avec une précision. La précision affecte la taille et l'utilisation du stockage. L'horodatage est stocké et géré au format UTC (Temps universel coordonné). Le type de données Timestamp doit comporter entre 3 et 9 octets, selon la précision utilisée. La ventilation suivante illustre le stockage utilisé par ce type de données : bit[0~13] année - 14 bits bit[14~17] mois - 4 bits bit[18~22] jour - 5 bits bit[23~27] heure - 5 bits [facultatif] bit[28~33] minute - 6 bits [facultatif] bit[34~39] seconde - 6 bits [facultatif] bit[40~71] fractionnaire seconde [facultatif avec longueur variable]
`UUID`	Remarque : Le type de données UUID est considéré comme un sous-type du type de données STRING. La taille de stockage est de 16 octets en tant que clé d'index. S'il est utilisé en tant que clé primaire, la taille de stockage est de 19 octets.
`ENUM`	Une énumération est représentée sous forme de tableau de chaînes. Les valeurs `ENUM` sont des identificateurs symboliques (jetons) stockés sous forme de petites valeurs entières représentant une position ordonnée dans l'énumération.
`ARRAY`	Collection triée de zéro élément ou de plusieurs éléments saisis. Les tableaux qui ne sont pas définis au format JSON ne peuvent pas contenir de valeurs `NULL`. Les tableaux déclarés au format JSON peuvent contenir n'importe quelle valeur JSON valide, y compris la valeur spéciale NULL, appropriée à JSON.
`MAP`	Ensemble non trié de zéro paire ou de plusieurs paires clé-élément, où toutes les clés sont des chaînes et tous les éléments sont du même type. Toutes les clés doivent être uniques. Les paires clé-élément sont appelées des champs (fields), les clés (field names) et les éléments associés (field values). Les valeurs de champ peuvent avoir des types différents, mais les correspondances ne peuvent pas contenir de valeurs de champ NULL.
`RECORD`	Ensemble fixe d'au moins une paire clé-élément, où toutes les clés sont des chaînes. Toutes les clés dans un enregistrement doivent être uniques.
`JSON`	Toutes les données JSON valides.

Cycles de vie et états de table

Apprenez-en davantage sur les différents états de table et sur leur signification (processus de cycle de vie des tables).

Chaque table passe par une série d'états différents de sa création à sa suppression. Par exemple, une table à l'état DROPPING ne peut pas passer à l'état ACTIVE, tandis qu'une table à l'état ACTIVE peut passer à l'état UPDATING. Vous pouvez suivre les différents états d'une table en surveillant son cycle de vie. Cette section décrit les différents états d'une table.

Description de la table state.png
Description du tableau de l'illustration : state.png

Etat de la table	Description
`CREATING`	La table est en cours de création. Elle n'est pas encore prête à l'emploi.
`UPDATING`	La table est en cours de mise à jour. Vous ne pouvez pas apporter d'autres modifications à la table tant qu'elle est dans cet état. Une table a l'état `UPDATING` : Les limites de la table sont en cours de modification l'évolution du schéma de la table, en ajoutant ou en supprimant un index.
`ACTIVE`	La table peut être utilisée lorsqu'elle est dans cet état. La table a peut-être été récemment créée ou modifiée, mais l'état de la table est désormais stable.
`DROPPING`	La table est en cours de suppression et n'est pas accessible.
`DROPPED`	La table a été supprimée et n'existe plus pour les activités de lecture, d'écriture ou de requête. Remarques : Une fois supprimée, vous pouvez recréer une table du même nom.

Débogage des erreurs d'instruction SQL dans la console OCI

Lorsque vous utilisez la console OCI pour créer une table à l'aide d'une instruction DDL, d'une instruction DML pour insérer ou mettre à jour des données ou d'une requête SELECT pour extraire des données, vous pouvez obtenir une erreur indiquant que votre instruction est Incomplète ou défectueuse dans l'un des scénarios courants suivants :

Si vous avez un point-virgule à la fin de votre instruction SQL.
S'il y a une erreur de syntaxe dans votre instruction SQL comme l'utilisation incorrecte de virgules, l'utilisation de tout caractère inutile dans l'instruction, etc.
En cas d'erreur d'orthographe dans l'instruction SQL dans l'un des mots-clés SQL ou dans la définition de votre type de données.
Si vous avez défini la colonne comme NOT NULL mais que vous ne lui avez pas affecté de valeur par défaut.
Si vous avez défini la colonne comme NOT NULL mais que vous ne lui avez pas affecté de valeur par défaut.

Comment gérer certaines erreurs incomplètes ou défectueuses lors de l'utilisation de la console OCI pour créer ou gérer des données :

Supprimez le point-virgule (le cas échéant) à la fin de l'instruction SQL.
Vérifiez si votre instruction SQL contient un caractère indésirable ou une ponctuation incorrecte.
Recherchez les fautes d'orthographe dans votre instruction SQL.
Vérifiez que toutes vos définitions de colonne sont complètes et correctes.
Vérifiez si vous avez défini une clé primaire pour votre table.

Si vous obtenez toujours une erreur après avoir éliminé certaines des situations possibles décrites ci-dessus, vous pouvez utiliser Cloud Shell pour exécuter la requête et capturer l'erreur exacte comme indiqué dans l'exemple ci-dessous.

Example : Getting the error message for a SELECT statement from the cloud shell

La commande summarize vérifie la syntaxe et renvoie un bref récapitulatif d'une instruction SQL.

Dans la console OCI, ouvrez Cloud Shell dans le menu supérieur droit.
Copiez votre instruction SQL SELECT (par exemple, query1.sql) dans une variable (SQL_SELECTSTMT).
Par exemple :
```
SQL_SELECTSTMT=$(cat ~/query1.sql | tr '\n' ' ')
```

Appelez la commande oci ci-dessous pour vérifier la syntaxe de l'instruction SQL SELECT.

Remarques :

Vous devez indiquer compartment_id pour cette instruction 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'

Vous obtiendrez ainsi l'erreur exacte dans votre instruction SQL.

Référence de langue de définition de données

En savoir plus sur l'utilisation du langage DDL dans Oracle NoSQL Database Cloud Service.

Créez, modifiez et supprimez des tables et des index à l'aide du langage DDL Oracle NoSQL Database Cloud Service.

Pour plus d'informations sur la syntaxe du langage DDL, reportez-vous au Guide DDL (Data Definition Language) de table. Ce guide présente le langage DDL pris en charge par le produit Oracle NoSQL Database sur site. Oracle NoSQL Database Cloud Service prend en charge une partie de cette fonctionnalité et les différences sont documentées dans la section Différences de langage DDL dans le cloud.

En outre, chaque pilote NoSQL <language> fournit une API permettant d'exécuter une instruction DDL. Pour écrire votre application, reportez-vous à Utilisation d'API pour créer des tables et des index dans Oracle NoSQL Database Cloud Service.

Instructions DDL standard

Voici quelques exemples d'instructions DDL communes :

Créer une table

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

Exemple :

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

Modifier la table

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

Exemple :

ALTER TABLE audience_info USING TTL 7 days

Créer un index

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

Exemple :

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

Supprimer la table

DROP TABLE [IF EXISTS] table-name

Exemple :

DROP TABLE audience_info

Reportez-vous aux guides de référence pour en obtenir la liste complète :

Différences dans le cloud

Le langage DDL du service cloud diffère de la description contenue dans le guide de référence comme suit :

Noms de table

Ils sont limités à 256 caractères alphanumériques et traits de soulignement.
Doit commencer par une lettre
Impossible d'inclure des caractères spéciaux
Les tables enfant ne sont pas prises en charge.

Concepts non pris en charge

Instructions DESCRIBE et SHOW TABLE
Index de texte intégral
Gestion des utilisateurs et des rôles
Régions sur site

Référence de langage de requête

En savoir plus sur l'utilisation d'instructions SQL pour la mise à jour et l'interrogation de données dans Oracle NoSQL Database Cloud Service.

Oracle NoSQL Database utilise le langage de requête SQL pour la mise à jour et l'interrogation des données dans les tables NoSQL. Pour connaître la syntaxe du langage de requête, reportez-vous à Référence SQL pour Oracle NoSQL Database.

Requêtes standard

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;

Différences de langage de requête dans le cloud

La prise en charge des requêtes du service cloud est différente de celle décrite dans le guide de référence comme suit :

Restrictions applicables aux expressions utilisées dans la clause SELECT

Oracle NoSQL Database Cloud Service prend en charge des expressions de regroupement ou des expressions arithmétiques dans les fonctions d'agrégation. Tous les autres types d'expression ne sont pas autorisés dans la clause SELECT. Par exemple, les expressions CASE ne sont pas autorisées dans la clause SELECT.

Chaque pilote de base de données NoSQL fournit une API permettant d'exécuter une instruction de requête.

Référence de plan de requête

Un plan d'exécution de requête est la séquence d'opérations qu'Oracle NoSQL Database effectue pour exécuter une requête.

Un plan d'exécution de requête est une arborescence d'itérateurs de plan. Chaque type d'itérateur évalue un type d'expression différent qui peut apparaître dans une requête. En général, le choix de l'index et le type de prédicats d'index associés peuvent avoir un effet considérable sur les performances des requêtes. Par conséquent, en tant qu'utilisateur, vous souhaitez souvent voir l'index utilisé par une requête et les prédicats qui y ont été propagés. Sur la base de ces informations, vous pouvez forcer l'utilisation d'un autre index via des conseils d'index. Ces informations sont contenues dans le plan d'exécution de la requête. Tous les pilotes Oracle NoSQL fournissent des API permettant d'afficher le plan d'exécution d'une requête.

Voici quelques-uns des itérateurs les plus courants et les plus importants utilisés dans les requêtes :

Itérateur de TABLE : un itérateur de TABLE est responsable des éléments suivants :

Analyse de l'index utilisé par l'interrogation (qui peut être l'index principal).
Appliquer les prédicats de filtrage propagés vers l'index
Extrayez les lignes auxquelles pointent les entrées d'index qualificatives si nécessaire. Si l'index couvre, l'ensemble de résultats de l'itérateur TABLE est un ensemble d'entrées d'index. Sinon, il s'agit d'un ensemble de lignes de table.

Remarques :

Un index est appelé index de couverture par rapport à une requête si la requête peut être évaluée en utilisant uniquement les entrées de cet index, c'est-à-dire sans avoir à extraire les lignes associées.

Itérateur SELECT : il est responsable de l'exécution de l'expression SELECT.

Chaque requête contient une clause SELECT. Chaque plan de requête dispose donc d'un itérateur SELECT. Un itérateur SELECT a la structure suivante :


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

L'itérateur SELECT comporte des champs tels que : "FROM", "WHERE", "FROM variable" et "SELECT expressions". "FROM" et "FROM variable" représentent la clause FROM de l'expression SELECT, WHERE représente la clause filter et "SELECT expression" représente la clause SELECT.

Itérateur RECEIVE : il s'agit d'un itérateur interne spécial qui sépare le plan de requête en 2 parties :

L'itérateur RECEIVE lui-même et tous les itérateurs situés au-dessus dans l'arborescence de l'itérateur sont exécutés au niveau du pilote.
Tous les itérateurs situés sous l'itérateur RECEIVE sont exécutés sur les noeuds de réplication (RN) ; ces itérateurs forment une sous-arborescence enracinée sur l'enfant unique de l'itérateur RECEIVE.

En général, l'itérateur RECEIVE agit en tant que coordinateur de requête. Il envoie son sous-plan aux IDE appropriés pour exécution et collecte les résultats. Il peut effectuer des opérations supplémentaires telles que le tri et l'élimination des doublons et propager les résultats vers ses itérateurs ancêtres (le cas échéant) pour un traitement ultérieur.

Types de distribution :

Un type de distribution indique comment la requête sera distribuée pour exécution entre les numéros de référence participant à une base de données Oracle NoSQL (magasin). Le type de distribution est une propriété de l'itérateur RECEIVE.

Les différents types de distribution sont les suivants :

SINGLE_PARTITION : une requête SINGLE_PARTITION indique une clé de shard complète dans sa clause WHERE. Par conséquent, son ensemble de résultats complet est contenu dans une seule partition, et l'itérateur RECEIVE enverra son sous-plan à un seul RN qui stocke cette partition. Une requête SINGLE_PARTITION peut utiliser l'index de clé primaire ou un index secondaire.
ALL_PARTITIONS : les requêtes utilisent l'index de clé primaire ici et n'indiquent pas de clé de shard complète. Par conséquent, si le magasin comporte M partitions, l'itérateur RECEIVE enverra M copies de son sous-plan à exécuter sur l'une des M partitions chacune.
ALL_SHARDS : les requêtes utilisent un index secondaire ici et n'indiquent pas de clé de shard complète. Par conséquent, si le magasin a N shards, l'itérateur RECEIVE enverra N copies de son sous-plan à exécuter sur l'un des N shards chacun.

Anatomie d'un plan d'exécution d'interrogation :

L'exécution de la requête a lieu par lots. Lorsqu'un sous-plan de requête est envoyé à une partition ou à un shard pour exécution, il s'exécute jusqu'à ce qu'une limite de batch soit atteinte. La limite de batch est un nombre d'unités de lecture consommées localement par la requête. La valeur par défaut est de 2000 unités de lecture (environ 2 Mo de données). Elle ne peut être réduite que via une option de niveau requête.

Lorsque la limite de lot est atteinte, tous les résultats locaux générés sont renvoyés à l'itérateur RECEIVE pour traitement ultérieur, avec un indicateur booléen indiquant si d'autres résultats locaux peuvent être disponibles. Si l'indicateur est défini sur Vrai, la réponse inclut les informations de reprise. Si l'itérateur RECEIVE décide de renvoyer la requête vers la même partition/le même shard, il inclura ces informations de reprise dans sa demande, de sorte que l'exécution de la requête redémarre au point où elle s'est arrêtée au cours du batch précédent. En effet, aucun état de requête n'est maintenu au niveau du RN une fois le batch terminé. Le lot suivant pour la même partition/shard peut avoir lieu au même RN que le lot précédent ou à un autre RN qui stocke également la même partition/shard.