Document IRIS Cloud – Guide du débutant et exemple : Partie I – Introduction et visite rapide

Si vous connaissez déjà Java (ou .Net) et avez peut-être aussi utilisé d’autres bases de données documentaires (ou cherchez à en utiliser une), mais que vous découvrez l’univers InterSystems, cet article devrait vous aider.

InterSystems IRIS Cloud Document est une base de données documentaire entièrement managée qui vous permet de stocker des documents JSON et de les interroger avec une syntaxe SQL familière, le tout sous la forme d’un service cloud géré par InterSystems.

Dans cette série de deux articles, je vais vous présenter :

• Partie I - Introduction et visite rapide (cet article)
  • Qu’est-ce que c’est ?
  • Démarrer un déploiement InterSystems IRIS Cloud Document
  • Faire une visite rapide du service via son interface utilisateur
• Partie II - Exemple d’application Java conteneurisée
  • Récupération des détails de connexion et du certificat TLS
  • Revue d’un exemple Java simple qui crée une collection, insère des documents et les interroge
  • Configuration et exécution de l’exemple Java conteneurisé de bout en bout

L’objectif est de vous offrir une première expérience fluide.

1. Qu’est-ce qu’InterSystems IRIS Cloud Document ?

Cloud Document est un service de base de données documentaire construit sur la plateforme de données InterSystems IRIS, exposé comme un service cloud managé. Vous travaillez avec des documents JSON stockés dans des collections, puis vous les interrogez à l’aide de SQL, ou via des pilotes spécifiques au langage (Java ou .NET).

Conceptuellement :

• Un document est un objet ou un tableau JSON.
• Une collection est un conteneur logique pour les documents et fournit des API pour insérer/obtenir/mettre à jour/supprimer/interroger.
• En arrière-plan, c’est le même moteur qui alimente d’autres services de données IRIS, donc vous pouvez utiliser SQL pour interroger les données documentaires dès que vous en avez besoin.

2. Démarrer un déploiement

Vous gérez Cloud Document via le portail InterSystems Cloud Services.

Étapes générales :

2.1 Créer un déploiement

• Connectez-vous au portail Cloud Services.
• [Au passage, vous avez besoin d’un abonnement au service, mais cela sort du cadre de cet article, car c’est plutôt un sujet commercial. Pour plus de détails, vous pouvez consulter la documentation de notre page Services ainsi que la page du service sur AWS Marketplace]
• Créez un nouveau déploiement IRIS Cloud Document.
• Choisissez la région, le nom, etc., puis laissez le déploiement se provisionner.

Par exemple :

Voici une courte vidéo qui le montre :

3. Visite rapide : téléverser du JSON, l’importer dans une collection, parcourir et interroger

La console web Cloud Document vous offre un excellent moyen de découvrir le service sans écrire une seule ligne de code. Le flux est le suivant : téléverser un fichier JSON → l’importer dans une collection → le parcourir avec le navigateur de collections → exécuter quelques requêtes SQL.

Vous trouverez ces pages dans l’interface web de votre déploiement ; cette page de la documentation décrit les mêmes étapes.

3.1 Téléverser un fichier JSON d’exemple

Créez localement un petit fichier colors.json, par exemple :

[ 
    {
        "name": "Red",
        "rgb": [255, 0, 0],
        "hex": "#FF0000"
    }, 
    {
        "name": "Green",
        "rgb": [0, 255, 0],
        "hex": "#00FF00"
    } ,
    {
        "name": "Blue",
        "rgb": [0, 0, 255],
        "hex": "#0000FF"
    }
] 

Dans l’interface du déploiement Cloud Document :

1. Allez sur la page Add and Manage Files.
2. Utilisez le bouton Upload et sélectionnez votre fichier colors.json.

Le fichier doit avoir un objet ou un tableau au niveau supérieur, ce qui est bien le cas dans notre exemple.

3.2 Importer le JSON dans une collection

Importez maintenant le fichier téléversé dans une collection Cloud Document :

1. Accédez à la page Collection Import dans l’interface du déploiement.
2. Sélectionnez votre fichier colors.json via Select file.
3. Pour Collection, soit :
   
   • choisissez une collection existante, soit
   • choisissez (Add new collection) et saisissez par exemple colors(Ici, j’ai cliqué sur Preview, ce qui affiche le contenu et résume qu’à l’import 3 documents seront ajoutés)
4. Cliquez sur Import.

Le service analysera le JSON et écrira chaque objet dans la collection colors. Si votre fichier est volumineux, cela peut prendre un peu plus de temps ; pour trois petits objets, c’est quasiment instantané.

Vous devriez voir un message popup vert indiquant 3 documents :

[Si vous obtenez un message popup rouge indiquant une erreur, cela peut être parce qu’il s’agit de votre premier import et que le « backend » du service est encore en phase de « warm-up ». En regardant la trace réseau, vous pourriez voir quelque chose comme :

... https response error StatusCode: 409, RequestID: ... , api error CodeArtifactUserPendingException: ERROR: Lambda is initializing your function. It will be ready to invoke shortly.

Et dans ce cas, vous pouvez l’ignorer, attendre un peu, puis réessayer peu après.]

3.3 Explorer les données avec le navigateur de collections

Une fois l’import terminé, allez sur la page Collection Browser et sélectionnez la collection colors. Vous devriez voir chaque document affiché au format JSON.

Quelques essais à faire :

• Cliquez sur les documents individuels (avec les boutons Previous et Next) et inspectez leur JSON.
• Vérifiez que tous les objets de votre fichier sont bien présents.
• Notez que les collections ne sont que des regroupements logiques ; vous pouvez avoir plusieurs collections avec des structures de documents très différentes.

Ce navigateur est un bon moyen de vérifier rapidement ce qui se trouve dans votre déploiement sans écrire de code.

3.4 Exécuter une requête SQL simple

Les documents Cloud Document vivent dans des collections, mais vous pouvez les interroger via SQL en utilisant JSON_TABLE (voir la documentation) pour projeter les données JSON sous forme tabulaire. Dans l’interface du déploiement, allez sur la page SQL Query Tools et exécutez des requêtes comme :

SELECT name, rgb, hex
FROM JSON_TABLE(colors FORMAT COLLECTION)

Ou par exemple, en utilisant davantage de fonctionnalités de JSON_TABLE :

SELECT c.name, c.hex 
FROM JSON_TABLE( 'colors', 
   '$[*]' COLUMNS ( 
         name VARCHAR(50) PATH '$.name', 
         hex VARCHAR(10) PATH '$.hex'
        ) 
  ) AS c 
ORDER BY c.name

Voilà le schéma de base : charger du JSON dans une collection, le parcourir comme des documents, puis l’interroger en SQL lorsque vous souhaitez le filtrer ou le joindre.

Voici une courte vidéo qui le montre :

Nous pouvons maintenant passer à l’article suivant, où nous verrons et expliquerons l’exécution d’une application Java, la connexion à notre service cloud et les interactions avec celui-ci.