Gestion des bases de données

Ce document présente les points d’attention et une check list lorsque vous avez une modification à faire sur un schéma de données d’une base de données ou la création d’une requête particulière MongoDB.

Gestion de l’ajout d’un champ

Si ce champ n’est pas « protégé » (non préfixé par « _ »), seuls les aspects indexations sont à suivre.

Si ce champ est « protégé » (préfixé par un « _ »), quelques règles d’usages sont à respecter :

  • Il est préfixé en base par « _ » afin de ne pas être en conflit avec des métadonnées externes (notamment pour le « content » du Unit)
  • Le nom dans la base doit être court (exemple: _us) afin de limiter l’empreinte mémoire et disque de ce champs tant pour les index que pour les données, tant pour MongoDB que pour ElasticSearch
  • Le nom du point de vue usage (externe et interne) doit être explicite (exemple: allunitups)
  • Il est préfixé d’un “#” pour permettre son interprétation par Vitam comme un champ protégé
  • Il cache l’implémentation réelle du champ

Pour les collections « Single », les champs protégés sont explicitement indiqués dans le fichier ParserTokens et ne produiront des erreurs que dans le Back-office.

Certains de ces champs sont interdits en update/insert (depuis l’extérieur), mais autorisés en interne.

La définition d’un tel champ « protégé » s’effectue ainsi :

  • common-database-vitam

    • common-database-public

      • BuilderToken.java : il contient un enum simple définisssant le champ (exemple: ALLUNITUPS(« allunitups »))

      • VitamFieldsHelper.java : il contient des helpers pour accéder directement à la représentation formelle (précédé du “#”) le champ (exemple: allunitups())

        Le QueryBuilder interdit les champs préfixés par « _ ». Il impose donc l’usage de la notation “#”.

    • commmon-database-private

      • ParserTokens.java : il contient la copie exacte de BuilderToken mais y ajoute les méthodes
        • notAllowedOnSet() qui interdit ou pas l’update/insert depuis l’extérieur. Ce check est réalisé par les API-internal via les VarNameAdapter.
        • getPROJECTIONARGS()* qui traduit du champ interne en champ externe. Cette fonction est utilisé par les deux ci-dessous.
        • isNotAnalyzed() qui indique si le champ n’est pas indexé
        • isAnArray() qui indique si le champ est un tableau
        • isSingleProtectedVariable désigne les variables de collections Single
        • isAnArrayVariable désigne les variables de collections Single ou Multiple
        • isSingleNotAnalyzedVariable désigne les variables de collections Single
      • VarNameAdapter.java pour Unit/ObjectGroup pour usage interne pour Unit/ObjectGroup
      • VarNameAdapterExternnal.java pour Unit/ObjectGroup pour usage externe (sécurité) pour Unit/ObjetGroup (default si non renseigné)
      • VarNameInsertAdapter.java pour Unit/ObjectGroup
      • VarNameUpdateAdapter.java pour Unit/ObjectGroup (devra être dupliqué en usage externe et interne : protection de certains champs)
      • SingleVarNameAdapter.java pour les collections hors Unit/ObjectGroup pour usage interne
      • SingleVarNameAdapterExternal.java pour usage externe (sécurité) pour les collections hors Unit/ObjectGroup (default si non renseigné)

metadata-core : Unit et ObjectGroup

  • MongoDbVarNameAdapter.java : autorise les update/insert sur les #protégés et traduit dans les champs définitifs définis dans MetadataDocument.java, Unit.java et ObjectGroup.java (exemple: #allunitups en _us)
  • MongoDbMetadataResponseFilter.java : récupère la réponse et retraduit en sens inverse un champs « _xxx » en son correspondant « #xxxxxxxxx » (exemple: _us en #allunitups)
  • MetadataDocument.java et Unit.java et ObjectGroup.java pour la définition des champs traduits en interne (formats courts comme « _us » et non « _unitsparents »)

Pour les autres collections

Elles s’appuient sur SingleVarNameAdapater et devraient avoir leurs propres extensions (comme MongoDbVarNameAdapter) ainsi que pour les retours (comme MongoDbMetadataResponseFilter)

Modification d’une collection : check list

  • Pour les champs protégés (préfix #)
    • Ajouter le champ dans les classes BuilderToken, VitamFieldsHelper, ParserTokens
    • Vérifier/Modifier les VarNameAdapter de la collection s’ils sont bien pris en compte (tant pour les cas Insert/Update interdits ou pas que pour la traduction dans le nom du champ final)
    • Modifier le ResponseFilter de la collection pour retraduire en #xxxxx la réponse
  • Pour tous les champs
    • Mettre à jour le schéma Json pour prendre en compte le nouveau champ et son type
    • Si ce champ est utilisé dans des requêtes MongoDB et/ou consitue une clef primaire modifier avec l’intégration les index techniques MongoDb (optimisation et unicité)