Utiliser des expressions Arcade

ArcGIS Arcade est un langage d’expression portable, léger et sécurisé, conçu pour être utilisé dans ArcGIS qui peut exécuter des calculs mathématiques, manipuler du texte et évaluer les instructions logiques. Il prend également en charge les expressions à plusieurs instructions, les variables et les instructions de contrôle du flux. Ce qui différencie particulièrement le langage Arcade des autres langages d’expression et de script est qu’il inclut les types de données d’entité et de géométrie. Arcade est souvent utilisé pour effectuer un calcul avec des champs de couche et une géométrie.

Remarques sur l'utilisation

  • Les expressions Arcade sont prises en charge dans les outils Détecter les incidents, Calculer un champ, Filtrer par expression, Apparier les champs, Joindre les entités, Créer des zones tampon et Reconstruire les traces.
  • Les expressions peuvent comporter des attributs issus des flux en entrée et des sources, ainsi que de valeurs qui décrivent l’analyse dans laquelle l’expression est configurée.
  • Dans le générateur d’expressions, les champs sont regroupés en catégories, appelées globaux. Développez les globaux pour afficher la liste des champs contenus. Les expressions ArcGIS Velocity font appel aux globaux suivants :
    • $feature - Dans tous les outils à l’exception de Join Features (Joindre les entités), ce global contient les champs attributaires des entités en entrée issues des flux et des sources. Des expressions qui utilisent des valeurs attributaires d’entité en sélectionnant des champs de ce groupe peuvent être générées.
    • $analytic - ce global contient des valeurs spécifiques de l’analyse, comme $analytic.AnalyticStartTime ou $analytic.AnalyticLastEndTime.
      • Pour convertir ces valeurs globales d'analyse d'un entier epoch (1646409900000) en une date, utilisez la fonction Arcade Date(). Pour plus de détails, reportez-vous à la rubrique Fonctions de date de la documentation ArcGIS Arcade.
    • $target - dans l’outil Join Features (Joindre des entités), pour l’expression Join Condition (Condition de jointure), ce global contient les champs attributaires du flux cible ou de la source.
    • $join - dans l’outil Join Features (Joindre des entités), pour l’expression Join Condition (Condition de jointure), ce global contient les champs attributaires de la source de jointure.
  • Accédez aux champs et composants de structure dans le générateur d’expressions Arcade.
    • Dans l’onglet Globals (Globaux) , accédez aux champs, variables et composants de la structure liée à cette catégorie, par exemple les catégories $feature, $analytic, $target ou $join.

      Accéder aux champs et variables d’une catégorie

    • Permet d’afficher les champs ou variables liés à cette catégorie.

      Répertorier les champs et variables liés à une catégorie

  • Fournissez vos propres exemples de valeurs pour les tests d’expression Arcade.
    • Arcade fournit des exemples de valeurs par défaut en fonction du type de champ. Par exemple, chacun des champs de type chaîne possède l’exemple de valeur Pacific. Toutefois, pour créer et tester une expression valide pour différents jeux de données, vous devez modifier les exemples de valeurs fournis pour un champ afin que l’expression Arcade puisse évaluer l’expression et renvoyer le type de données correct renvoyé par l’expression.
    • Pour ajuster les exemples de valeurs pour les tests d’expression Arcade, procédez comme suit :
      • Cliquez sur la flèche pour accéder aux champs ou variables d’un regroupement ($join, $analytic, $target, $join).
      • Cliquez sur le bouton de mise à jour pour mettre à jour le champ souhaité.

        Cliquez sur le bouton de mise à jour pour fournir des exemples de valeurs pour les champs.

      • Ajustez l’exemple de valeur utilisé dans les tests et évaluations d’expression Arcade.

        Mettre à jour les exemples de valeurs utilisés dans la logique d’expression Arcade

      • L’expression Arcade est maintenant évaluée en fonction des exemples de données mis à jour fournis une fois que vous avez cliqué sur Test (Tester).
  • Créez des expressions Arcade capables de gérer les valeurs nulles et les valeurs 0.
    • Dans les opérations mathématiques, le langage d’expression Arcade traite les valeurs nulles comme des valeurs 0 pour l’évaluation. C’est pourquoi les expressions mathématiques Arcade créées dans ArcGIS Velocity doivent tenir compte des valeurs nulles de vos données.
    • Vous devez donc y incorporer la gestion des valeurs nulles. Examinons l’expression $feature.DistanceToFeature <= 5. Il convient de créer cette expression dans le langage Arcade de sorte qu’elle gère les valeurs nulles telles que $feature.DistanceToFeature != null && $feature.DistanceToFeature <= 5. Dans ce type d’expression, <= 5 est une opération mathématique. Si donc la valeur du champ DistanceToFeature est nulle, elle est évaluée comme une valeur 0 compatible avec l’expression.

Exemples d’opérations et de fonctions mathématiques

Les expressions peuvent traiter les nombres mathématiquement. Le tableau ci-dessous présente des exemples d’opérations disponibles. Pour plus d’informations sur les opérations mathématiques dans Arcade, reportez-vous à la rubrique Fonctions mathématiques.

Opérateur

Explication

Exemple

Résultat

a + b

a plus b.

Le champ fieldname (nom du champ) contient la valeur 1,5

$target["fieldname"] + 2.5

4.0

a - b

a moins b.

Le champ fieldname (nom du champ) contient la valeur 3,3

$target["fieldname"]- 2.2

1.1

a * b

a multiplié par b.

Le champ fieldname (nom du champ) contient la valeur 2,0

$join["fieldname"] * 2.2

4.4

a / b

a divisé par b.

Le champ fieldname (nom du champ) contient la valeur 4,0

$join["fieldname"] / 1.25

3.2

abs( a )

Renvoie la valeur absolue (positive) de a.

Le champ fieldname (nom du champ) contient la valeur -1,5

abs($target["fieldname"])

1,5

log ( a )

Renvoie le logarithme naturel (base E) de a.

Le champ fieldname (nom du champ) contient la valeur 1

log($join["fieldname"])

0

sin ( a )

Renvoie le sinus trigonométrique de a. On suppose que l'entrée est un angle en radians.

Le champ fieldname (nom du champ) contient la valeur 1,5707

sin($target["fieldname"])

1

cos( a )

Renvoie le cosinus trigonométrique de a. On suppose que l'entrée est un angle en radians.

Le champ fieldname (nom du champ) contient la valeur 0

cos($join["fieldname"])

1

tan( a )

Renvoie la tangente de a. On suppose que l'entrée est un angle en radians.

Le champ fieldname (nom du champ) contient la valeur 0

tan($target["fieldname"])

0

sqrt( a )

Renvoie la racine carrée de a.

Le champ fieldname (nom du champ) contient la valeur 9

sqrt($join["fieldname"])

3

min( a, b )

Renvoie la valeur la plus basse entre a et b.

Le champ fieldname (nom du champ) contient les valeurs 1,5 et -3

min($join["fieldname"], -3)

-3

max( a, b )

Renvoie la valeur la plus élevée entre a et b.

Le champ fieldname1 (nom du champ 1) contient la valeur 1,5 et le champ fieldname2 (nom du champ 2) contient la valeur -3

max($target["fieldname1"], $join["fieldname2"])

1,5

constrain(<value>,<low>,<high>)

Renvoie la valeur en entrée si elle est comprise dans les limites de contrainte. Si la valeur en entrée est inférieure à la valeur basse, elle renvoie la valeur basse. Si la valeur en entrée est supérieure à la valeur haute, elle renvoie la valeur haute.

constrain($target["distance"], 0, 10)

constrain($join['Store dist'], 6, distance)

Renvoie 0 si la distance est inférieure à 0, 10 si la distance est supérieure à 10 et la distance dans les autres cas.

Renvoie 6 si la distance du point de vente est inférieure à 6, la distance si la distance du point de vente est supérieure à la distance, et la distance du point de vente dans les autres cas.

L’exemple de multiplication suivant pour une expression de condition de jointure utilisant un champ du jeu de données cible :

$target["Distance"] * 2 > $join["DistField"]

Exemples de fonctions de texte

Les expressions Arcade peuvent traiter du texte. Le tableau ci-dessous présente des exemples d’opérations disponibles. Pour en savoir plus sur les fonctions de texte dans Arcade, reportez-vous à la rubrique Fonctions de texte.

Opérateur

Explication

Exemple

Résultat

concatenate(<valeurs>, <séparateur>)

Concatène les valeurs et renvoie une chaîne.

  • values : une matrice de valeurs de chaînes à concaténer.
  • separator (facultatif) : séparateur à utiliser pour la concaténation si le paramètre values (valeurs) est une matrice, ou une chaîne à concaténer si une valeur unique est fournie pour le premier paramètre. Si elle n’est pas renseignée, elle sera vide.

Le champ fieldname (nom du champ) contient une valeur ArcGIS Velocity

concatenate([$target["fieldname"], "is", "great!"], ' ')

ArcGIS Velocity est formidable !

find(<searchText>, <text>, <startPos>)

Trouve une chaîne à l’intérieur d’une chaîne. Les caractères génériques ne sont pas pris en charge.

  • searchText : sous-chaîne à rechercher.
  • text : le texte à rechercher.
  • startPos (facultatif) : l’index en base zéro de l’emplacement dans la chaîne où s’effectue la recherche.

Le champ fieldname1 (nom du champ 1) contient la valeur 14NorthStreet et le champ fieldname2 (nom du champ 2) contient la valeur North

find($target["fieldname2"], $join["fieldname1"])

2

lower(<value>)

Convertit une chaîne en minuscule.

  • value : chaîne à convertir en minuscules.

Le champ fieldname (nom du champ) contient la valeur ANALYTICS

lower($join["fieldname"])

analyse

L’exemple de texte suivant utilise la recherche et inférieur :

find(("north"), lower("146NorthStreet")) == False

Exemples de fonctions de date

Arcade peut traiter des dates. Le tableau ci-dessous présente des exemples d’opérations disponibles. Pour en savoir plus sur les fonctions de date dans Arcade, reportez-vous à la rubrique Fonctions de date.

Dans Arcade, les valeurs de mois vont de 0 (janvier) à 11 (décembre), les jours vont de 1 à 31, les heures vont de 0 (minuit) à 23 (23 h), les minutes et secondes vont de 0 à 59 et les millisecondes, de 0 à 999.

Opérateur

Explication

Exemple

Résultat

date( <value>, <month>, <day>, <hour>, <minute>)

Analyse une valeur ou un ensemble de valeurs dans une chaîne de date.

  • value (facultatif) : nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC ou nombre représentant une année. Si une année est spécifiée, le mois et le jour doivent être également renseignés dans les paramètres suivants. Cette valeur peut également être une chaîne de date ou une chaîne ISO 8601 à convertir en date.
  • month (facultatif) : mois (de 0 à 11), où 0 correspond à janvier et 11 à décembre.
  • day (facultatif) : jour du mois (1 à 31).
  • hour (facultatif) : heure de la journée (0 à 23).
  • minute (facultatif) : minute de l’heure (0 à 59).
  • second (facultatif) : seconde de la minute (0 à 59).
  • millisecond (facultatif) : milliseconde de la seconde (0 à 999).

Le champ fieldname (nom du champ) contient la valeur 1476987783555

Exemple 1 : Date($target["fieldname"])

Exemple 2 : Date(2017,0,14,0)

Exemple 3 : Date()

Exemple 1 : 20 oct 2016 11:23:03

Exemple 2 : 14 Jan 2017 00:00:00

Exemple 3 : renvoie l’heure actuelle

DateDiff(<date1>, <date2>, <unités>)

Opère une soustraction entre deux dates et renvoie la différence dans les unités spécifiées.

  • date1 : la valeur de date à partir de laquelle on soustrait une deuxième date.
  • date2 : la valeur de date à soustraire de la première date indiquée.
  • startpos (facultatif) : les unités dans lesquelles renvoyer la différence entre les deux dates données. Les unités prises en charge sont les millisecondes, les secondes, les minutes, les heures, les jours, les mois et les années. Les millisecondes sont la valeur par défaut.

Exemple 1 : DateDiff(Date(2017,1,14,0), Date())

Exemple 2 : DateDiff(Date(2017,1,14,0), Date(), "Years")

Le résultat est fonction de la date à laquelle vous exécutez la commande.

Exemple 1 : -20532129137

Exemple 2 : -0,6546783768647119

Year(<dateValue>)

Renvoie l'année de la date donnée.

  • value : une valeur de date à partir de laquelle on récupère l’année.

Exemple 1 : le champ fieldname (nom du champ) est un champ de type Date avec la valeur 09 Oct 2017 04:30:43 pm

Year($join["fieldname"])

Exemple 2 : le champ fieldname (nom du champ) est un champ de type chaîne formaté comme chaîne ISO 8601 avec la valeur 2012-09-27

Exemple 2 : le champ fieldname (nom du champ) est un champ de type chaîne formaté comme chaîne ISO 8601 avec la valeur Year(Date($target["fieldname"]))

Exemple 1 : 2017

Exemple 2 : 2012

Opérateurs conditionnels

Les instructions conditionnelles peuvent utiliser les opérateurs suivants :

Opérateur

Explication

Exemple

Résultats

a > b

a < b

a est supérieur à b.

a est inférieur à b.

10 > 2

False

a >= b

a <= b

a est supérieur ou égal à b.

a est inférieur ou égal à b.

abs(-10) >= 10

True

a != b

a est différent de b.

abs(-3) != -3

True

a == b

a est égal à b.

abs(-5) == 5

True

<condition1> || <condition2>

La condition 1 ou la condition 2 est satisfaite.

(abs(-5) == 5) || (10 < 2)

True

<condition1> && <condition2>

La condition 1 et la condition 2 sont satisfaites.

(abs(-5) == 5) && (10 < 2)

False

L’exemple suivant d’expression de zone tampon utilise des conditions et fonctions avancées :

iff(field1 > field2, iff(field2 = 0, field3, field4), 0)

L’exemple suivant est un exemple de multiplication pour une condition de jointure :

iff(field1 > field2, iff(field2 = 0, field3, field4), 0) > $join["Distance"] * 2

Exemples d’opérateurs logiques

Outre les opérateurs conditionnels, des opérateurs logiques plus avancés peuvent être utilisés pour créer des expressions, comme illustré dans le tableau ci-dessous. Pour en savoir plus sur les fonctions logiques dans Arcade, reportez-vous à la rubrique Fonctions logiques.

Fonction

Explication

Exemple

Résultat

iff(<condition>,<true value>,<false value>)

Renvoie une valeur si une condition est true (vrai) et renvoie une autre valeur si la condition est false (faux).

Les éléments <true value> et <false value> peuvent être :

  • Un champ numérique. Si le nom du champ renferme un espace, utilisez des crochets.
  • Un nombre.
  • Une fonction.

iff($feature["field1"] > $feature["field2"], $feature["field1"], 0)

iff($feature["field1"] > $feature["field2"], iff($feature["field2"] = 0, $feature["field3"], $feature["field4"]), 0)

Renvoie field1 (champ 1) si field1 (champ 1) est supérieur à field2 (champ 2) et 0 dans les autres cas.

Renvoie le résultat de la deuxième fonction iff si field1 (champ 1) est supérieur à field2 (champ 2) et 0 dans les autres cas.

when(<expression1> , <result1> , <expression2> , <result2> , ... , <expressionN> , <resultN>, <default>)

Évalue une série d’expressions dans l’ordre jusqu’à ce que l’une soit true (vrai).

  • expression : une expression.
  • result : résultat de l’expression. Il peut s’agir d’un nombre ou d’un champ.
  • default : une valeur facultative si les expressions ne font l’objet d’aucune correspondance.

when(($feature["field1"] + 10) > 1, 1,($feature["field2"] + 10) > 2 , 2, $feature["field3"])

Si field1 (champ 1) + 10 est supérieur à 1, renvoie 1. Sinon, l’expression vérifie si field2 (champ 2) + 10 est supérieur à 2. Renvoie 2 si c'est le cas. Si ce n’est pas le cas, renvoie field3 (champ 3).

decode(<conditional val> , <case1> , <result1>, <case2>, <result2>, ... <caseN>, <resultN>, <defaultValue> )

Évalue une expression et compare sa valeur aux paramètres suivants. Si l’expression correspond, elle renvoie la valeur du paramètre suivant. Si aucune correspondance n’est trouvée, le dernier paramètre peut être une valeur de renvoi par défaut.

  • conditional val : valeur conditionnelle. Il peut s’agir d’un champ ou d’une expression.
  • case : une valeur à comparer à la valeur conditionnelle.
  • result : le résultat si le cas correspond à la valeur conditionnelle.
  • defaultValue : valeur facultative si aucune autre valeur n’est définie sur true (vrai).

decode($feature["field1"] + 3 , $feature["field1"], 1, $feature["field2"], 2, 0)

Compare l’égalité entre la valeur conditionnelle field1 (champ 1) + 3 et case1 (cas 1) field1 (champ 1). Si la condition est true (vrai), renvoie 1. Si la condition est false (faux), compare l’égalité entre field1 (champ 1) + 3 et field2 (champ 2). Si la condition est true (vrai), renvoie 2 ; sinon, renvoie 0.