Définir des paramètres dans une couche de requête

L'instruction SQL qui définit la source d'une couche de requête est statique. Toutefois, il peut arriver que des parties d’instructions SQL ne soient pas connues à l’avance. Par exemple, lorsque vous affichez des précipitations agrégées, vous ne savez pas forcément si le lecteur de la carte souhaitera agréger les valeurs des stations pluviométriques par jour, semaine ou mois. Les paramètres dans les couches de requête rendent les composants de l'instruction SQL dynamiques. Vous pouvez considérer un paramètre de requête comme une variable d’instruction SQL dont la valeur est définie au moment de l’exécution de la requête. Voici les deux types de paramètres de requête :

• Les paramètres de plage connectent des valeurs numériques ou temporelles dynamiquement aux curseurs de plage et temporel. Prenons l’exemple d’une requête SQL comportant un paramètre de plage WHERE ::r:myRangeVar1. La requête SQL qui est envoyée à la base de données est WHERE aField = value ou WHERE aField => value1 AND aField <= value2, selon qu’une ou deux valeurs sont transmises par le curseur de plage.
• Les paramètres discrets mettent à jour une requête avec des valeurs littérales au moment de l'exécution de la requête. Prenons l’exemple d’une requête SQL qui définit une couche de requête et inclut deux paramètres discrets : WHERE city_population > ::population AND state_name = ::name. Lorsque des valeurs, telles que 10000 et California sont spécifiées pour chaque paramètre, respectivement, la requête SQL qui est envoyée à la base de données est WHERE city_population > 10000 AND state_name = 'California'.

Remarque :

Une couche de requête est définie par une requête SQL spécifiée au moment de créer une couche de requête pour les données d’une base de données relationnelle ou de créer une couche de requête pour les données d’un entrepôt de données cloud. Vous pouvez également créer une couche de requête à l’aide de l’outil de géotraitement Créer une couche de requête, mais cet outil ne permet pas de définir des paramètres. Pour utiliser des paramètres dans l'instruction SQL, modifiez la couche de requête dans la boîte de dialogue Modifier la couche de requête.

Si vous avez besoin d’une couche de requête vous permettant de parcourir des valeurs agrégées par date, heure, ou plages numériques, utilisez l’outil de géotraitement Créer une couche de requête d’agrégation pour créer la couche de requête en activant l’agrégation dynamique et définissez les paramètres de requête pour afficher vos résultats.

Définir les paramètres de plage

Les paramètres de plage fonctionnent avec des valeurs numériques (entières ou doubles) ou des valeurs date-heure pour afficher dynamiquement les données sur le curseur de plage ou le curseur temporel. Elles sont déclarées sans référence à un champ ou à une expression, et aucun opérateur logique n'est utilisé dans la requête SQL. Le champ ou l'expression est en revanche défini en tant que propriété du paramètre. Le mot-clé ::r: est ajouté en préfixe aux paramètres de plage. Vous utilisez les paramètres de plage lorsque la clause WHERE de la requête SQL repose sur des champs qui ne font pas partie de la liste SELECT.

WHERE ::r:MyRangeParameter, en est un exemple

Lorsque vous déclarez un paramètre de plage, vous devez spécifier un champ ou une expression, le type de données et parfois, les valeurs par défaut et un alias à utiliser dans les curseurs. Cliquez sur Valeur par défaut pour saisir les valeurs par défaut minimum et maximum. Lorsque cette case est cochée, vous devez saisir au moins une valeur pour valider l'expression. Les valeurs par défaut peuvent être littérales (une date ou un nombre réel) ou une expression qui renvoie une valeur du type de données spécifié.

Les étapes suivantes expliquent comment définir en tant que période par défaut un paramètre de plage dans une table nommée earthquakes (tremblements de terre) afin d’afficher les tremblements de terre qui se sont produits au cours des sept derniers jours, et, le cas échéant, comment utiliser le curseur temporel pour modifier cette période :

1. Sous l'onglet Carte du groupe Couche, ouvrez le menu Ajouter des données et cliquez sur Couche de requête.
2. Dans le menu Connection (Connexion), choisissez une connexion à une base de données ou créez une connexion à l’aide de New Geodatabse Connection (Nouvelle connexion à une géodatabase) .
3. Dans le champ Nom, saisissez Tremblements de terre.
4. Dans la zone Requête, saisissez select * from EARTHQUAKES where ::r:EQDateRange.
5. Pointez la souris sur le paramètre ::r:EQDateRange dans le code et cliquez sur Edit Query (Modifier la requête) pour mettre à jour les propriétés.
6. Fournissez les propriétés de paramètre suivantes :
   1. Pour Champ ou expression, saisissez le nom d'un champ date-heure.
   2. Pour Type de données, choisissez Date.
   3. Sélectionnez Valeur par défaut.
   4. Fournissez des expressions de valeurs par défaut en fonction de la base de données sous-jacente.

      Vous trouverez des exemples de certaines bases de données dans le tableau ci-dessous. Reportez-vous à la rubrique Configurations de base de données et de client pour les couches de requête pour obtenir la liste complète des bases de données configurables pour utiliser les couches de requête.

   Base de données	Valeur début	Valeur fin
   Microsoft SQL Server	dateadd(dd, -7, cast(getdate() as date))	cast(getdate() as date)
   Oracle	trunc(CURRENT_DATE) - INTERVAL '7' DAY	trunc(CURRENT_DATE)
   PostgreSQL	CURRENT_DATE - INTERVAL '7 days'	CURRENT_DATE

7. Cliquez sur Done (Terminé).
8. Cliquez sur Valider pour vérifier que la requête SQL et les définitions de plage sont valides.
9. Cliquez sur Next (Suivant).
10. Spécifiez Unique Identifier Fields (Champs d’identifiant unique), Geometry Type (Type de géométrie), et Spatial Reference (Référence spatiale), puis cliquer sur Finish (Terminer).

Vous pouvez désormais utiliser le curseur temporel pour accéder à n'importe quelle période et afficher les tremblements de terre qui ont eu lieu. Vous pouvez cliquer sur le bouton Désactiver l'heure pour afficher les tremblements de terre compris dans la plage temporelle par défaut établie, c'est-à-dire au cours des sept derniers jours dans cet exemple.

Attention :

Vous pouvez déclarer plusieurs paramètres de plage dans une couche de requête, mais un seul de ces paramètres de plage peut référencer des valeurs date-heure.

Propriétés avancées pour les paramètres de plage

En cas d'échec de la validation de la requête, vous pouvez spécifier certaines propriétés avancées pour les paramètres de plage. Développez la section Avancé des propriétés d'un paramètre pour spécifier le nom de la table auquel le champ appartient. Ceci permet d'extraire les valeurs minimum et maximum directement de la table. Vous bénéficiez ainsi d'une efficacité optimale, en particulier si le paramètre se trouve au sein d'une requête imbriquée. En outre, sous l'en-tête Avancé, si aucune valeur par défaut n'a été fournie, vous devez spécifier l'expression à utiliser lorsque la valeur n'est pas indiquée pour le paramètre. Choisissez 1=1 (valeur par défaut), ce qui définit le paramètre sur 'TRUE' dans l’expression ou 1=0, ce qui définit le paramètre sur 'FALSE'.

Paramètres discrets

Les paramètres discrets fonctionnent avec des valeurs numériques (entières ou doubles), de date ou de chaîne et le mot-clé :: est ajouté en préfixe. Elles sont appariées à un champ ou à une expression à l'aide des opérateurs SQL. Vous pouvez mettre à jour la valeur de champ pour filtrer les données qui sont affichées sur la carte.

Lorsque vous déclarez un paramètre discret, vous devez préciser un type de données et des valeurs par défaut. Pour fournir une liste de choix dans la couche au moment de l’exécution, utilisez l’opérateur SQL IN et sélectionnez Allow multiple values (Autoriser les valeurs multiples). Vous pouvez également spécifier un alias à utiliser à la place du nom du paramètre. Voici quelques exemples :

• WHERE aFieldName = ::var1
• WHERE AdminField IN ::AdminAgency

Paramètres discrets prédéfinis

Vous avez la possibilité de déclarer vos propres paramètres discrets ; il existe deux paramètres discrets prédéfinis que vous pouvez utiliser dans vos requêtes. Le paramètre view_extent spécifie un filtre spatial pour votre requête et peut améliorer de manière significative la performance lorsque vous travaillez avec des jeux de données très volumineux. Le paramètre view_scale vous permet d’accéder à l’échelle actuelle de la carte dans la requête. Ces variables ne sont prises en compte que dans le contexte d’une carte 2D. Elles seront ignorées dans une scène 3D.

view_extent

Lorsqu’une couche est visualisée sur une carte, un filtre spatial est ajouté à la fin de la requête SQL envoyée à la base de données. Ceci est suffisant, mais vous pouvez souhaiter limiter l’agrégation aux entités visibles dans l’étendue actuelle. Dans ces cas, vous pouvez ajouter le paramètre view_extent à la requête pour la limiter spatialement à l’étendue actuelle.

Vous pouvez ajouter ::view_extent n’importe où dans votre requête, autant de fois que nécessaire. À la différence des paramètres discrets personnalisés, il n’y a aucune propriété à définir, et la valeur par défaut du paramètre est NULL.

La requête SQL qui est envoyée à la base de données remplace ::view_extent par un polygone au format de texte connu (WKT) dans la même référence spatiale que la couche. Utilisez une fonction propre aux bases de données et un ID de référence spatiale (SRID) pour créer une géométrie à partir du polygone d’étendue WKT. Cela est illustré dans les exemples suivants pour les bases de données de type SQL Server et PostgreSQL :

• Dans SQL Server : WHERE shape.STWithin(geometry::STGeomFromText(::view_extent, 4326)) = 1
• Dans PostgreSQL : WHERE ST_Within(shape, ST_GeomFromText(::view_extent, 4326))

view_scale

Utilisez le paramètre prédéfini view_scale lorsque vous souhaitez modifier la clause where ou les champs sélectionnés sur la base de l’échelle actuelle de la carte. La valeur par défaut zéro est transmise lorsque vous utilisez ce paramètre. Il n’y a aucune autre propriété à définir. Vous pouvez spécifier ce paramètre autant de fois que nécessaire dans votre requête SQL. Les exemples suivants utilisent le paramètre view_scale dans les bases de données de type SQL Server et PostgreSQL :

• Dans SQL Server : WHERE IIF(::view_scale > 100000, <do this>, <do that>)
• Dans PostgreSQL : WHERE (CASE WHEN ::view_scale >= 100000 THEN <do this> WHEN ::view_scale >= 50000 AND ::view_scale < 100000 THEN <do that> ELSE <do the other thing> END)

Ajouter des paramètres à une couche de requête

Pour ajouter un paramètre à la requête, procédez comme suit :

1. Cliquez avec le bouton droit sur la couche dans la fenêtre Contenu et sélectionnez Propriétés .
2. Sous l’onglet Source, dans la ligne Query (Requête) de la table, cliquez sur Edit Query (Modifier la requête) .

   La requête est exprimée dans la zone de texte Requête.

   Conseil :

   Pour faciliter la lecture du texte de la requête, vous pouvez l’agrandir en appuyant sur la touche Ctrl et en tournant la molette de la souris vers l’avant.

3. Positionnez le pointeur dans le code et saisissez ::r:<name> pour entrer un paramètre de plage, ou ::<name> pour entrer un paramètre discret.

   Les paramètres apparaissent en gras dans la requête SQL et un bouton Edit (Modifier) s’affiche en regard.

4. Cliquez sur le bouton Edit (Modifier) pour accéder aux propriétés du paramètre.
5. Définissez les propriétés du paramètre et cliquez sur Terminé.

   Vous devez définir une Default Value (Valeur par défaut) et un Data Type (Type de données). Les autres propriétés sont facultatives.

6. Dans la boîte de dialogue Modifier la couche de requête, cliquez sur Valider pour vérifier qu'aucune erreur n'est présente.
7. Poursuivez la configuration des propriétés spatiales de la couche et cliquez sur Terminer lorsque vous avez terminé.