# 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é)