Nous sommes heureux d’annoncer Trevas 2.4.0, qui ajoute le support d’Apache Spark 4 via le nouveau module vtl-spark4.

Si vous souhaitez faire évoluer vos applications clientes basées sur Spark vers Spark 4, vous pouvez dépendre de fr.insee.trevas:vtl-spark4 avec le reste de la stack Trevas. L’API et le comportement VTL restent les mêmes ; seule la couche d’intégration Spark change.

Spark 3 n’est pas abandonné. Le module vtl-spark existant reste pleinement maintenu en parallèle. Vous pouvez rester sur Spark 3 aussi longtemps que nécessaire — il n’y a pas d’échéance de migration imposée.

Voir les notes de version 2.4.0 et la release GitHub pour le détail des changements.

Applications clientes Trevas — imports ANTLR empaquetés​

Maintenir Spark 3 et Spark 4 sur la même base de code Trevas nous a aussi amenés à affiner le packaging d’ANTLR : le runtime est désormais empaqueté (shade) et relocalisé pour que Trevas et Spark ne se disputent plus les mêmes classes org.antlr.v4 sur le classpath.

À partir de Trevas 2.4.0, cette note ne concerne que les applications clientes qui utilisent explicitement les API ANTLR dans leur propre code (lexer, flux de jetons, arbre de parse, listeners, etc.) en plus de Trevas. Si votre application n’appelle que les API Trevas et n’importe ni ne manipule jamais les types ANTLR directement, rien ne change pour vous.

Si vous manipulez ANTLR vous-même — que vous restiez sur Apache Spark 3 (vtl-spark) ou que vous passiez à Spark 4 (vtl-spark4) — vous devez importer le runtime depuis l’espace de noms relocalisé :

import fr.insee.vtl.antlr.runtime.*;
import fr.insee.vtl.antlr.runtime.tree.*;
// … et les autres sous-paquets fr.insee.vtl.antlr.* selon les besoins

Auparavant, le code qui touchait le parseur ou les API ANTLR utilisait souvent les paquets ANTLR standard, par exemple :

import org.antlr.v4.runtime.*;
import org.antlr.v4.runtime.tree.*;

Ces imports ne correspondent plus aux classes livrées par Trevas à l’exécution. Trevas empaquette org.antlr:antlr4-runtime dans l’artefact vtl-antlr et relocalise org.antlr.v4 → fr.insee.vtl.antlr afin que Trevas et Spark puissent partager une JVM sans charger deux runtimes ANTLR concurrents.

Ce qu’il faut modifier​

• Mettre à jour chaque import org.antlr.v4… de votre application (et tout code généré contre les types du parseur Trevas) vers le paquet fr.insee.vtl.antlr… correspondant.
• S’appuyer sur fr.insee.trevas:vtl-antlr (de façon transitive via vtl-parser / vtl-engine) pour le runtime ; ne pas ajouter une dépendance séparée sur org.antlr:antlr4-runtime pour l’analyse liée à Trevas.
• Cela vaut autant pour l’intégration Spark 3 que Spark 4 : les deux utilisent la même pile parseur empaquetée.

Correspondance typique :

Pour plus de détails techniques, voir ici la documentation.

Trevas 2.0.0 is released!

Following the implementation of DAGs and the reordering of VTL instructions before execution, evaluating a VTL script will integrate this new functionality by default.

A technical documentation is available to describe this feature and how to disable it.

Trevas 1.7.0 met à niveau VTL en version 2.1.

Cette version introduit deux nouveaux opérateurs :

• random
• case

random produit un nombre décimal entre 0 et 1.

case permet de définir des déclarations multiconditionnelles plus claires, par exemple:

ds2 := ds1[ calc c := case when r < 0.2 then "Low" when r > 0.8 then "High" else "Medium" ]

Les deux opérateurs sont déjà disponibles dans Trevas !

La nouvelle grammaire fournit également des opérateurs temporels et inclut des corrections, sans aucun changement radical par rapport à la version 2.0.

Voir la section coverage pour plus de détails.

Nouveautés​

Trevas 1.6.0 introduit le module VTL Prov.

Ce module permet de produire des métadonnées de lineage à partir de Trevas, basées sur les ontologies RDF : PROV-O et SDTH.

Aperçu du modèle SDTH​

Modèle adopté​

Le module vtl-prov, version 1.6.0, utilise le modèle partiel suivant :

Des améliorations arriveront dans les prochaines semaines.

Outils disponibles​

Les outils de provenance Trevas sont documentés ici.

Exemple​

Cas d'utilisation métier​

Deux jeux de données sources sont transformés pour produire des jeux de données transitoires et un jeu de données final permanent.

Entrées​

ds1 & ds2 métadonnées:

Script VTL​

ds_sum := ds1 + ds2;
ds_mul := ds_sum * 3;
ds_res <- ds_mul[filter mod(var1, 2) = 0][calc var_sum := var1 + var2];

Modèle RDF cible​

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX prov: <http://www.w3.org/ns/prov#>
PREFIX sdth: <http://rdf-vocabulary.ddialliance.org/sdth#>

# --- Program and steps
<http://example.com/program1> a sdth:Program ;
    a prov:Agent ; # Agent? Or an activity
    rdfs:label "My program 1"@en, "Mon programme 1"@fr ;
    sdth:hasProgramStep <http://example.com/program1/program-step1>,
                        <http://example.com/program1/program-step2>,
                        <http://example.com/program1/program-step3> .

<http://example.com/program1/program-step1> a sdth:ProgramStep ;
    rdfs:label "Program step 1"@en, "Étape 1"@fr ;
    sdth:hasSourceCode "ds_sum := ds1 + ds2;" ;
    sdth:consumesDataframe  <http://example.com/dataset/ds1>,
                            <http://example.com/dataset/ds2> ;
    sdth:producesDataframe <http://example.com/dataset/ds_sum> .

<http://example.com/program1/program-step2> a sdth:ProgramStep ;
    rdfs:label "Program step 2"@en, "Étape 2"@fr ;
    sdth:hasSourceCode "ds_mul := ds_sum * 3;" ;
    sdth:consumesDataframe <http://example.com/dataset/ds_sum> ;
    sdth:producesDataframe <http://example.com/dataset/ds_mul> .

<http://example.com/program1/program-step3> a sdth:ProgramStep ;
    rdfs:label "Program step 3"@en, "Étape 3"@fr ;
    sdth:hasSourceCode "ds_res <- ds_mul[filter mod(var1, 2) = 0][calc var_sum := var1 + var2];" ;
    sdth:consumesDataframe <http://example.com/dataset/ds_mul> ;
    sdth:producesDataframe <http://example.com/dataset/ds_res> ;
    sdth:usesVariable   <http://example.com/variable/var1>,
                        <http://example.com/variable/var2> ;
    sdth:assignsVariable <http://example.com/variable/var_sum> .

# --- Variables
# i think here it's not instances but names we refer to...
<http://example.com/variable/id1> a sdth:VariableInstance ;
                                  rdfs:label "id1" .
<http://example.com/variable/var1> a sdth:VariableInstance ;
                                  rdfs:label "var1" .
<http://example.com/variable/var2> a sdth:VariableInstance ;
                                  rdfs:label "var2" .
<http://example.com/variable/var_sum> a sdth:VariableInstance ;
                                  rdfs:label "var_sum" .

# --- Data frames
<http://example.com/dataset/ds1> a sdth:DataframeInstance ;
    rdfs:label "ds1" ;
    sdth:hasName "ds1" ;
    sdth:hasVariableInstance    <http://example.com/variable/id1>,
                                <http://example.com/variable/var1>,
                                <http://example.com/variable/var2> .

<http://example.com/dataset/ds2> a sdth:DataframeInstance ;
    rdfs:label "ds2" ;
    sdth:hasName "ds2" ;
    sdth:hasVariableInstance    <http://example.com/variable/id1>,
                                <http://example.com/variable/var1>,
                                <http://example.com/variable/var2> .

<http://example.com/dataset/ds_sum> a sdth:DataframeInstance ;
    rdfs:label "ds_sum" ;
    sdth:hasName "ds_sum" ;
    sdth:wasDerivedFrom <http://example.com/dataset/ds1>,
                        <http://example.com/dataset/ds2> ;
    sdth:hasVariableInstance    <http://example.com/variable/id1>,
                                <http://example.com/variable/var1>,
                                <http://example.com/variable/var2> .

<http://example.com/dataset/ds_mul> a sdth:DataframeInstance ;
    rdfs:label "ds_mul" ;
    sdth:hasName "ds_mul" ;
    sdth:wasDerivedFrom <http://example.com/dataset/ds_sum> ;
    sdth:hasVariableInstance    <http://example.com/variable/id1>,
                                <http://example.com/variable/var1>,
                                <http://example.com/variable/var2> .

<http://example.com/dataset/ds_res> a sdth:DataframeInstance ;
    rdfs:label "ds_res" ;
    sdth:wasDerivedFrom <http://example.com/dataset/ds_mul> ;
    sdth:hasVariableInstance    <http://example.com/variable/id1>,
                                <http://example.com/variable/var1>,
                                <http://example.com/variable/var2>,
                                <http://example.com/variable/var_sum> .

Nouveautés​

Trevas 1.4.0 introduit le module VTL SDMX.

Ce module permet de consommer des sources de métadonnées SDMX pour instancier les structures de données et les ensembles de données Trevas.

Il permet également d'exécuter les VTL TransformationSchemes pour obtenir les ensembles de données persistants résultants.

Aperçu​

Trevas prend en charge les éléments de message SDMX ci-dessus. Seul l'élément VtlMappingSchemes est facultatif.

Les éléments de la case 1 sont utilisés pour produire des Trevas DataStructures, en valorisant les attributs des composants VTL : name, role, type, nullable et valuedomain.

Les éléments de la case 2 sont utilisés pour générer le code VTL (ensembles de règles et transformations).

Utilitaires disponibles​

Les utilitaires de Trevas SDMX sont documentés ici.

Dépannage​

Voir cette section.

Opérateurs temporels de Trevas​

La version 1.4.0 de Trevas introduit un support préliminaire pour les types de date et d'heure et les opérateurs.

La spécification décrit les types temporels tels que date, time_period, time et duration. Cependant, les auteurs de Trevas trouvent ces descriptions peu satisfaisantes. Cet article de blog décrit nos choix de mise en œuvre et en quoi ils diffèrent des spécifications.

Dans la spécification, time_period (et les types date) est décrit comme un type composé avec un début et une fin (ou un début et une durée). Cela complique la mise en œuvre et apporte peu de valeur au langage car on peut simplement fonctionner directement sur une combinaison de dates ou de date et de durée. Pour cette raison, nous avons défini une algèbre entre les types temporels et n'avons pas encore implémenté le type time_period.

La fonction period_indicator s'appuie sur la connaissance des périodes pour les types qui ne sont pas suffisamment définis pour le moment pour être implémentés.

Représentation Java​

Le type VTL date est représenté en interne comme le type java.time.Instant, java.time.ZonedDateTime et [java.time.OffsetDateTime](https://docs.oracle.com/en%2Fjava%2Fjavase%2F11%2Fdocs%2Fapi%2F%2F/java.base/java/time/OffsetDateTime.html#: ~:text=OffsetDateTime%20is%20an%20immutable%20representation,be%20stored%20in%20an%20OffsetDateTime%20.)

Instant représente un moment précis dans le temps. Notez que ce type n'inclut pas les informations de fuseau horaire et est donc non utilisable avec tous les opérateurs. On peut utiliser les types ZonedDateTime et OffsetDateTime lorsque la sauvegarde du fuseau horaire est nécessaire.

Le type de VTL durée est représenté en interne comme le type org.troisten.extra.PeriodDuration du package threeten extra. Il représente une durée utilisant à la fois des unités calendaires (années, mois, jours) et une durée temporelle (heures, minutes, secondes et nanosecondes).

Fonction flow_to_stock​

La fonction flow_to_stock convertit un ensemble de données avec interprétation par flux en une interprétation par stock. Cette transformation est utile lorsque vous souhaitez agréger des données de flux (par exemple, taux de ventes ou de production) en données de stock cumulées (par exemple, inventaire total).

Syntaxe:

résultat:= flow_to_stock(op)

Paramètres:

• op - L'ensemble de données d'entrée avec interprétation du flux. L'ensemble de données doit avoir un identifiant de type time, des identifiants additionels, et au moins une mesure de type number.

Résultat:

La fonction renvoie un ensemble de données avec la même structure que celui en entrée, mais avec les valeurs converties en stock.

Fonction stock_to_flow​

La fonction stock_to_flow convertit un ensemble de données avec interprétation de stock en une interprétation de flux. Ce La transformation est utile lorsque vous souhaitez dériver des données de flux à partir de données de stock cumulées.

Syntaxe:

résultat:= stock_to_flow(op)

Paramètres:

• op - L'ensemble de données d'entrée avec interprétation par stock. L'ensemble de données doit avoir un identifiant de type time, des identifiants additionels, et au moins une mesure de type number.

Résultat:

La fonction renvoie un ensemble de données avec la même structure que celui en entrée, mais avec les valeurs converties en flux.

Fonction timeshift​

La fonction timeshift décale la composante temporelle d'une plage de temps spécifiée dans l'ensemble de données. Ceci est utile pour analyser des données à différents décalages temporels, par exemple en comparant les valeurs actuelles aux valeurs passées.

Syntaxe:

résultat := timeshift(op, shiftNumber)

Paramètres:

• op - Ensemble de données contenant des séries chronologiques.
• shiftNumber - Un entier représentant le nombre de périodes à décaler. Les valeurs positives évoluent dans le temps, tandis que les valeurs négatives reculent.

Résultat:

La fonction renvoie un ensemble de données avec les identifiants temporels décalés du nombre de périodes spécifiées.

Nouveautés​

Trevas 1.2.0 permet le support de Java 17.

Gestion des modules Java​

Spark ne supporte pas les modules Java.

Les applications clientes en Java 17 embarquant Trevas doivent configurer les UNNAMED modules pour Spark.

Maven​

Ajouter à votre fichier pom.xml, dans la section build > plugins :

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <compilerArgs>
            <arg>--add-exports</arg>
            <arg>java.base/sun.nio.ch=ALL-UNNAMED</arg>
        </compilerArgs>
    </configuration>
</plugin>

Docker​

ENTRYPOINT ["java", "--add-exports", "java.base/sun.nio.ch=ALL-UNNAMED", "mainClass"]

Nouveautés​

Trevas 1.2.0 inclut le support des assignements persistants : ds1 <- ds;.

Dans Trevas, les datatsets persistants sont représentés par PersistentDataset.

Gérer PersistentDataset​

Les datasets Trevas sont représentés par Dataset.

Après avoir executé le moteur Trevas, vous pouvez utiliser les datasets persistants comme suit :

Bindings engineBindings = engine.getContext().getBindings(ScriptContext.ENGINE_SCOPE);
engineBindings.forEach((k, v) -> {
    if (v instanceof PersistentDataset) {
        fr.insee.vtl.model.Dataset ds = ((PersistentDataset) v).getDelegate();
        if (ds instanceof SparkDataset) {
            Dataset<Row> sparkDs = ((SparkDataset) ds).getSparkDataset();
            // Do what you want with sparkDs
        }
    }
});

Nouveautés​

La validation hiérarchique est implémentée dans Trevas 1.1.0, via les opérateurs define hierarchical ruleset et check_hierarchy.

Exemple​

Données en entrée​

ds1:

Script VTL​

// Ensure ds1 metadata definition is good
ds1 := ds1[calc identifier id := id, Me := cast(Me, integer)];

// Define hierarchical ruleset
define hierarchical ruleset hr (variable rule Me) is
    My_Rule : ABC = A + B + C errorcode "ABC is not sum of A,B,C" errorlevel 1;
    DEF = D + E + F errorcode "DEF is not sum of D,E,F";
    HIJ : HIJ = H + I - J errorcode "HIJ is not H + I - J" errorlevel 10
end hierarchical ruleset;

// Check hierarchy
ds_all := check_hierarchy(ds1, hr rule id all);
ds_all_measures := check_hierarchy(ds1, hr rule id always_null all_measures);
ds_invalid := check_hierarchy(ds1, hr rule id always_zero invalid);

Données en sortie​

• ds_all

• ds_always_null_all_measures

• ds_invalid

Trevas Batch 0.1.1 utilise la version 1.0.2 de Trevas.

Ce batch Java permet d'obtenir des métriques d'exécutions Trevas en mode Spark.

Le fichier de configuration à renseigner est décrit de le README du projet. Le lancement du batch produiera un fichier Markdown en sortie.

Lancement​

Local​

java -jar trevas-batch-0.1.1.jar -Dconfig.path="..." -Dreport.path="..."

L'exécution java se fera en Spark local.

Kubernetes​

Des objets Kubernetes par défaut sont définis dans le dossier .kubernetes.

Alimenter le fichier config-map.yml puis lancer le job dans votre cluster.