Processeur Expression

Le processeur est versatile. Il peut comprendre une expression comme étant un argument et afficher le résultat dans un champ.

L'expression peut être composée des éléments suivants :

• des identifiants ;

• des littéraux (nombres, littéraux textuels, booléens et mots-clés) ;

• des opérateurs ;

• des fonctions.

Prérequis

Le processeur Expression se montre le plus utile en mode évaluation (c'est-à-dire qu'il "calcule et retourne le résultat de l'expression"). Ce mode est activé en commençant l'expression par un signe égal (=). En l'absence de ce signe, le processeur n'évaluera pas l'expression et la reproduira simplement dans le champ de résultat.

Le signe (=) devant être placé au début des expressions sera omis de l'ensemble des exemples ci-dessous.

Configurer le processeur

Pour définir les paramètres du processeur Expression, suivez les indications du tableau ci-dessous.

Label	Description	Obligatoire
Expression	Modèle d'expression	oui
Champ de sortie	Champ dans lequel l'expression sera appliquée. Il peut s'agir d'un champ existant choisi dans la liste ou d'un champ créé à cette fin (dans ce cas, choisissez Saisir du texte dans la liste et écrivez le nom du nouveau champ dans la zone de texte en dessous).	oui

Formuler une expression

Une expression est une instruction à destination du processeur pour qu'il réalise une opération et retourne la valeur dans une colonne, nouvelle ou existante, du jeu de données.

Ces expressions ressemblent à ce qu'on appelle des "formules" dans un tableur type Excel. La principale différence est qu'au lieu de référencer des cellules (par ex. A1 + B2), le processeur peut réaliser des opérations à partir des valeurs situées dans des colonnes données (par ex. column_1 + column_2).

Comme les formules, les expressions peuvent combiner divers éléments. Le processeur Expression prend en charge les éléments suivants :

• les identifiants (par ex. un nom de champ comme column_1 ou un nom de champ verrouillé comme $column_1) ;

• les littéraux :

  • les nombres (par ex. 2 ou 3.6) ;

  • les littéraux textuels (par ex. "hello" ou 'world') ;

  • les booléens (par ex. 'true' ou 'false') ;

  • les mots-clés (par ex. une constante mathématique comme pi ou e) ;

• les opérateurs (par ex. +, OR, not, <=) ;

• les fonctions (par ex. now(), sin(nombre), startswith("hello', 'he')).

Les identifiants

La principale fonctionnalité du processeur Expression est sa capacité à réaliser des opérations dans les colonnes d'un enregistrement. L'identifiant technique (ou nom de champ) d'une colonne peut être utilisé dans une expression afin d'accéder aux valeurs contenues dans ce champ pour l'enregistrement actuel. Cet identifiant technique peut être trouvé dans les options de champ, sous le Nom du champ concerné.

Exemples :

• column_1 pour accéder à un champ nommé column_1 (et peut-être intitulé "Column 1")

• name_en pour accéder à un champ nommé name_en (et peut-être intitulé "Name (EN)")

Important

Dans certains cas, le nom du champ peut être ambigu, par exemple, s'il s'agit d'un nombre ou d'un mot-clé réservé (comme "pi", la constante mathématique, ou "e", le nombre d'Euler), ou encore s'il commence par un nombre.

Pour forcer le processeur Expression à évaluer un identifiant comme un nom de champ, il est possible d'ajouter le signe dollar ($) devant un identifiant. Le signe dollar peut être utilisé avec n'importe quel nom de champ, mais il n'est obligatoire que pour les noms de champ ambigus.

Exemples :

• $column_1 pour accéder à un champ nommé column_1 (et peut-être intitulé "Column 1")

• $name_en pour accéder à un champ nommé name_en (et peut-être intitulé "Name (EN)")

• $20_to_25_yo pour accéder à un champ nommé 20_to_25_yo (et peut-être intitulé "20 to 25 years old")

• $33 pour accéder à un champ intitulé 33

• $pi pour accéder à un champ intitulé pi

Tout nombre ou littéral textuel peut être remplacé dans les exemples suivants par un nom de champ contenant des données du même type. Le processeur Expression extraira la valeur de la colonne spécifiée et s'en servira pour exécuter l'opération requise.

Une même expression peut contenir plusieurs champs (ou le même champ réutilisé plusieurs fois).

Expressions littérales

Les littéraux tels que les nombres, les littéraux textuels (entre guillemets simples ou doubles), les booléens et les mots-clés peuvent être utilisés dans n'importe quelle expression.

Exemples :

• 3

• 2.5

• "Hello" ou 'Hello'

• 'A bigger sentence'

• 'true' ou 'false'

• pi, PI ou Pi

• e ou E

Opérateurs

Les opérateurs sont des symboles qui se comportent généralement comme des fonctions, mais sont utilisés avec une syntaxe plus naturelle.

Le processeur Expression prend en charge trois types d'opérateurs, en fonction du nombre de paramètres qui les entourent :

• les opérateurs unaires peuvent être utilisés comme préfixes ou suffixes pour modifier la valeur d'1 expression ;

• les opérateurs binaires peuvent être des opérateurs arithmétiques pour réaliser un calcul avec 2 expressions, ou des opérateurs booléens pour comparer le résultat de 2 expressions ;

• l'opérateur ternaire pour convertir une expression conditionnelle en 1 ou 2 résultats possibles.

Remarque

Les opérateurs devraient être placés dans l'ordre suivant : factorielle, exponentielle, signe, division euclidienne, évaluation de fonction, multiplication/division, addition/soustraction, concaténation, not, comparaison, and, or, opérateur ternaire, opérateur ternaire sans else.

Opérateurs unaires

Opérateur	Description	Exemple
-	Préfixe rendant la valeur suivante négative	- 4, - [expression]
not, ! (not)	Opérateur booléen qui inverse la condition suivante	not('true') ou !('true') retourne false not(4 > 5) est true !(5 <= 10) est false
! (factorielle)	Suffixe qui calcule la factorielle d'une expression	3! retourne 1*2*3

Opérateurs binaires

Opérateur	Description	Exemple
+, -, *, /, %, //, ^	Opérateurs arithmétiques : ajouter, soustraire, multiplier, diviser, modulo, division euclidienne, puissance	2 + 3 retourne 5 5 - 8 retourne -3 9 * 3 retourne 27 15 / 6 retourne 2.5 15 % 6 retourne 3 15 // 6 retourne 2 2 ^ 3 retourne 8 column_1 + column2
and, &&, or, || (retournent un booléen)	Opérateurs boléens : and, or	'true' and 'true' est true 'true' && 'false' est false 'true' or 'false' est true 'false' || 'false' est false
>, <, >=, <=, ==, !=	Opérateurs de comparaison : supérieur à, inférieur à, supérieur ou égal à, inférieur ou égal à, égal à et différent de retournent un booléen	3 < 4 est true 5 >= 10 est false
&	Opérateur de concaténation des chaînes de caractères	'Hello' & ' world' retourne 'Hello world'

Opérateur ternaire

L'expression [condition] ? [résultat si vrai] : [résultat si faux] s'appelle l'opérateur ternaire et permet de retourner différents résultats en fonction d'une condition.

Remarque

Une expression ternaire peut être lue comme "si [condition] alors [résultat si vrai] sinon [résultat si faux]".

Exemples :

• 'true' ? 'hello' : 'goodbye' retourne 'hello'

• 'false' ? 'hello' : 'goodbye' retourne 'good bye'

• 4 > 3 ? '4 is bigger' : '3 is bigger' retourne '4 is bigger'

• 10 <= 9 ? '9 is bigger' : '10 is bigger' retourne '10 is bigger'

La dernière partie de l'opérateur ternaire est optionnelle, ce qui veut dire que les expressions suivantes sont aussi valides :

• 'true' ? 'hello' retourne 'hello'

• 'false' ? 'hello' retourne un résultat vide

Remarque

Certaines opérations peuvent échouer si elles concernent un champ dont la plateforme a mal deviné le type à la création du jeu de données, même si le type de champ a été modifié ultérieurement. Veuillez contacter l'équipe support Opendatasoft si cela se produit.

Fonctions

Les fonctions sont utilisées pour réaliser des opérations plus avancées dans une expression. Elles acceptent 0 ou plus paramètres et leur appliquent des transformations telles que :

• gestion du texte ;

• fonctions mathématiques ;

• gestion de la date et de l'heure.

Gestion du texte

Fonctions booléennes

Fonction	Description	Exemple
isalpha([texte])	Vrai si le texte ne contient que des lettres
isnumeric([texte])	Vrai si le texte ne contient que des chiffres
isalnum([texte])	Vrai si le texte contient des lettres ou des chiffres
isdecimal([texte])	Vrai si le texte est un nombre décimal valide
isdigit([texte])	Vrai si le texte est un chiffre seul
islower([texte])	Vrai si le texte est en minuscules
isupper([texte])	Vrai si le texte est en majuscules
empty([texte])	Vrai si le texte est vide
contains([texte],[texte]), startswith([texte],[texte]), endswith([texte],[texte])	Vrai si le texte (1er argument) contient, commence ou finit par le texte (2e argument)	contains("hello", "l") retourne True startswith("hello", 'he') retourne True endswith("hello", 'he') retourne False

Fonctions de traitement

Fonction	Description	Exemple
length([texte])	Retourne la longueur du texte	length('bonjour') retourne 7
lower([texte]), upper([texte])	Convertit le texte en minuscules ou en majuscules
capitalize([texte]), capitalize_all([texte])	Met la première lettre du texte en majuscule ou la première lettre de chaque mot
ljust([texte],[nombre],[texte]) rjust([texte],[nombre],[texte]) center([texte],[nombre],[texte])	Justifie à gauche, à droite et au centre un texte (1er argument), jusqu'à atteindre le [nombre] de caractères à l'aide d'un autre texte (3e argument)	ljust("4400", 5, "0") retourne "44000" rjust("4400", 5, "0") retourne "04400" center("4400", 6,"0") retourne "044000"
normalize([texte])	Remplace un texte par sa représentation ASCII	normalize("你好") retourne "ni hao"
substring([texte],[nombre],[nombre])	Extrait une sous-chaîne de texte, en commençant à l'index indiqué par le 2nd argument et d'une longueur indiquée par le 3e argument (optionnel).	substring('hello', 1, 3) retourne "ell"
count([texte], [texte])	Retourne le nombre de fois où le 2nd argument apparaît dans le 1er argument	count("Hello world", "l") retourne 3
left([texte],[nombre]) right([texte],[nombre]) mid([texte],[nombre])	Extrait une partie du texte (1er argument) en partant de la gauche, de la droite ou du milieu ; la taille de l'extrait est déterminé par le 2nd argument pour gauche et droite, par les 2nd et 3e arguments pour mid	left("hello", 2) retourne "he" right("hello", 3) retourne "llo" mid("hello", 2, 3) retourne "ell"

Fonctions mathématiques

Fonction	Description	Exemple
abs([nombre])	Valeur absolue	abs(-4) retourne 4
sqrt([nombre])	Racine carrée
floor([nombre]), ceil([nombre])	Fonctions arrondi à l'entier inférieur et supérieur	floor(4.6) retourne 4 ceil(3.3) retourne 4
max([nombre],[nombre]), min([nombre],[nombre])	Fonctions minimales et maximales
round([nombre])	Arrondit à l'entier le plus proche	round(4.6) retourne 5 round(3.3) retourne 4
random([nombre])	Génère un nombre aléatoire (entre 0 et [nombre])	random(10) retourne par exemple 7.27846540481
pow([nombre], [nombre])	Fonction puissance	pow(2, 3) retourne 8
exp([nombre]), log([nombre]), log10([nombre])	Fonctions exponentielles, logarithmiques et du logarithme en base 10	exp(1) retourne E
radians([nombre])	Convertit un angle de degrés en radians	radians(180) retourne PI
degrees([nombre])	Convertit un angle de radians en degrés	degrees(PI) retourne 180
cos([nombre]), cosh([nombre]), sin([nombre]), sinh([nombre]), tan([nombre]), tanh([nombre])	Cosinus, cosinus hyperbolique, sinus, sinus hyperbolique, tangente, tangente hyperbolique (en radians)	sin(PI) retourne 0
acos([nombre]), acosh([nombre]), asin([nombre]), asinh([nombre]), atan([nombre]), atanh([nombre])	Cosinus inverse, cosinus inverse hyperbolique, sinus inverse, cosinus inverse hyperbolique, tangente inverse, tangente inverse hyperbolique (en radians)	acos(0) retourne PI/2

Gestion de la date et de l'heure

Fonction	Description	Exemple
year([datetime]), quarter([datetime]), month([datetime]), week([datetime]), day([datetime]), dayofweek([datetime]), hour([datetime]), minute([datetime]), second([datetime])	Extrait l'année, le trimestre, le mois, la semaine, la date, le jour de la semaine, les heures, les minutes et les secondes d'un datetime	year("2014-06-07") retourne 2014 hour("2014-06-07 17:00") retourne 17 hour("2014-06-07 17:00", "Europe/Paris") retourne 19 Imaginez que la date actuelle est "2021-04-21". Dans ce cas, month(now()) renvoie 4.
add_years([datetime],[nombre]), add_months([datetime],[nombre]), add_days([datetime],[nombre]), add_hours([datetime],[nombre]), add_minutes([datetime],[nombre]), add_seconds([datetime],[nombre])	Ajoute des années, des mois, des jours, des heures, des minutes ou des secondes à un datetime	add_months("2014-11-14", 3) renvoie 2015-02-14. Imaginez que la date actuelle est "2021-04-21". Dans ce cas, add_months(now(), 3) renvoie 2021-07-21.
fromtimestamp([nombre])	Convertit un indicateur temporel en datetime
quartertodaterange([nombre])	Convertit un trimestre en intervalle de dates	quartertodaterange("2014Q2") retourne "2014-04-01 / 2014-06-30"
datediff([datetime], [datetime], [unité])	Compte le nombre d'unités entre deux expressions datetime. [unité] peut être être "year", "month", "day", "hour", "minute" ou "second".	datediff("2014-02-28", "2015-02-28", "month") retourne 12 datediff("2014-02-28T20:00:00Z", "2014-02-28T21:00:00Z", "minute") retourne 60 Imaginez que la date actuelle est "2021-04-21". Dans ce cas, datediff("2020-04-01", now(), "year") renvoie 1.