Rechercher un module

La méthode findKey recherche un seul enregistrement par sa clé.

Par exemple, le code suivant recherche un enregistrement avec une clé de 42 dans le module Personnes / Organisations :

use IMu::Module; # ⋯ my $parties = IMu::Module->new('eparties', $session); my $hits = $parties->findKey(42); 

La méthode retourne le nombre de correspondances trouvées, qui est soit 1 si l’enregistrement existe, soit 0 s’il n’existe pas.

La méthode findKeys recherche un ensemble de valeurs clés. Les clés sont passées sous la forme d’une référence à un tableau

my $parties = IMu::Module->new('eparties', $session); my $keys = [52, 42, 17]; my $hits = $parties->findKeys($keys); 

La méthode retourne le nombre d’enregistrements trouvés.

La méthode findTerms est le moyen le plus flexible et le plus puissant de rechercher des enregistrements dans un module. Il peut être utilisé pour exécuter des requêtes simples d’un seul terme ou des recherches complexes de plusieurs termes.

Les termes sont spécifiés à l’aide d’un objet IMu::Terms. Une fois qu’un objet IMu::Terms a été créé, ajoutez-y des termes spécifiques (à l’aide de la méthode add), puis passez l’objet IMu::Terms à la méthode findTerms. Par exemple, pour spécifier une recherche dans Personnes / Organisations pour les enregistrements dont le prénom est John et le nom de famille Smith :

use IMu::Terms;  my $search = IMu::Terms->new(); $search->add('NamFirst', 'John'); $search->add('NamLast', 'Smith');  my $hits = $parties->findTerms($search); 

Il y a plusieurs points à noter :

1. Le premier argument passé à la méthode add contient le nom de la colonne ou un alias dans le module à rechercher.
2. Un alias associe une valeur fournie à une ou plusieurs colonnes réelles. Les alias sont créés à l’aide des méthodes addSearchAlias ou addSearchAliases.
3. Le deuxième argument contient la valeur à rechercher.
4. Facultativement, un opérateur de comparaison peut être fourni comme troisième argument (voir l’exemple ici). L’opérateur précise comment la valeur fournie comme deuxième argument doit être mise en correspondance. Les opérateurs sont les mêmes que ceux utilisés en TexQL (voir Guide du langage de requête Texpress pour plus de détails). S’il n’est pas fourni, l’opérateur utilise par défaut « matches ». Il ne s’agit pas d’un véritable opérateur TexQL, mais il est traduit par le moteur de recherche comme l’opérateur le plus « naturel » pour le type de colonne recherché. Par exemple, pour les colonnes texte, « matches » est traduit par l’opérateur TexQL contains et pour les colonnes entières, il est traduit par l’opérateur TexQL =.

Note: À moins qu’il ne soit vraiment nécessaire de spécifier un opérateur, envisagez d’utiliser l’opérateur matches, ou mieux encore de ne pas fournir d’opérateur du tout, car cela permet au serveur de déterminer le meilleur type de recherche.

Exemples

1. Pour rechercher le nom Smith dans le champ nom du module Personnes / Organisations, le terme suivant peut être utilisé :

   my $search = IMu::Terms->new(); $search->add('NamLast', 'Smith'); 

2. Spécifier des termes de recherche pour d’autres types de colonnes est simple. Par exemple, pour rechercher des enregistrements insérés le 4 avril 2011 :

   my $search = IMu::Terms->new(); $search->add('AdmDateInserted', 'Apr 4 2011'); 

3. Pour rechercher des enregistrements insérés avant le 4 avril 2011, il est nécessaire d’ajouter un opérateur :

   my $search = IMu::Terms->new(); $search->add('AdmDateInserted', 'Apr 4 2011', '<'); 

4. Par défaut, la relation entre les termes est un booléen AND. Cela signifie que pour trouver des enregistrements qui correspondent à la fois à un prénom contenant John et à un nom de famille contenant Smith, l’objet IMu::Terms peut être créé comme suit :

   my $search = IMu::Terms->new(); $search->add('NamFirst', 'John'); $search->add('NamLast', 'Smith'); 

5. Un objet IMu::Terms où la relation entre les termes est un booléen OR peut être créé en passant la valeur d’énumération 'OR' au constructeur IMu::Terms :

   my $search = IMu::Terms->new('OR'); $search->add('NamFirst', 'John'); $search->add('NamLast', 'Smith');

   Cela spécifie une recherche d’enregistrements où le prénom contient Smith ou le nom de famille contient John.

6. Des combinaisons de termes de recherche AND et OR peuvent être créées. La méthode addAnd ajoute un nouvel ensemble de termes AND à l’objet IMu::Terms d’origine. De même, la méthode addOr ajoute un nouvel ensemble de termes OR. Par exemple, pour restreindre la recherche d’un prénom John et d’un nom de famille Smith aux enregistrements correspondants insérés avant le 4 avril 2011 ou le 1er mai 2011, spécifiez :

   my $search = IMu::Terms->new(); $search->add('NamFirst', 'John'); $search->add('NamLast', 'Smith'); my $dates = $search->addOr(); $dates->add('AdmDateInserted', 'Apr 4 2011', '<'); $dates->add('AdmDateInserted', 'May 1 2011'); 

7. Pour lancer une recherche, passez l’objet IMu::Terms à la méthode findTerms :

   my $parties = IMu::Module->new('eparties', $session); my $search = IMu::Terms->new(); $search->add('NamLast', 'Smith'); my $hits = $parties->findTerms($search); 

   Comme avec les autres méthodes de recherche, la valeur retournée contient le nombre estimé de correspondances.

8. Pour utiliser un alias de recherche, appelez la méthode addSearchAlias pour associer l’alias à un ou plusieurs noms de colonnes réels avant d’appeler findTerms. Supposons que nous voulons autoriser un utilisateur à effectuer une recherche de mots-clés dans le module Catalogue. Notre définition d’une recherche par mots-clés est de rechercher les colonnes SummaryData, CatSubjects_tab et NotNotes. Nous pourrions le faire en construisant une recherche OR :

   my $keyword = '⋯'; # ⋯ my $search = IMu::Terms->new('OR'); $search->add('SummaryData', $keyword); $search->add('CatSubjects_tab', $keyword); $search->add('NotNotes', $keyword);

   Une autre façon de faire est d’enregistrer l’association entre le nom keywords et les trois colonnes qui nous intéressent, puis de passer le nom keywords comme colonne à rechercher :

   my $keywor d = '⋯'; # ⋯ my $catalogue = IMu::Module->new('ecatalogue', $session); my $columns = [ 'SummaryData', 'CatSubjects_tab', 'NotNotes' ]; $catalogue->addSearchAlias('keywords', $columns); # ⋯ my $search = IMu::Terms->new(); $search->add('keywords', $keyword); $catalogue->findTerms($search);

   Une alternative au passage des colonnes sous forme de référence à un tableau de chaînes consiste à passer une seule chaîne, les noms des colonnes étant séparés par des points-virgules :

    my $keyword = '⋯'; # ⋯  my $catalogue = IMu::Module->new('ecatalogue', $session); my $columns = 'SummaryData;CatSubjects_tab;NotNotes'; $catalogue->addSearchAlias('keywords', $columns); # ⋯ my $search = IMu::Terms->new(); $search->add('keywords', $keyword); $catalogue->findTerms($search); 

   L’avantage de l’utilisation d’un alias de recherche est qu’une fois l’alias enregistré, un nom simple peut être utilisé pour spécifier une recherche OR plus complexe.

9. Pour ajouter plusieurs alias à la fois, créez une table de hachage de noms et de colonnes et appelez la méthode addSearchAliases :

   my $aliases = { 'keywords' => 'SummaryData;CatSubjects_tab;NotNotes', 'title' => 'SummaryData;TitMainTitle' }; $catalogue->addSearchAliases($aliases); 

Avec la méthode findWhere, il est possible de soumettre une clause TexQL complète where :

my $parties = IMu::Module->new('eparties', $session); my $where = "NamLast contains 'Smith'"; my $hits = $parties->findWhere($where); 

Bien que cette méthode offre un contrôle total sur la façon exacte dont une recherche est menée, il est généralement préférable d’utiliser findTerms pour soumettre une recherche plutôt que de construire une clause where. Il y a (au moins) deux raisons de préférer findTerms à findWhere :

1. La construction de la clause where nécessite que le code ait une connaissance détaillée du type de données et de la structure de chaque colonne. La méthode findTerms laisse cette tâche au serveur. Par exemple, il est simple de spécifier le terme permettant de rechercher une valeur particulière dans une table imbriquée. Pour trouver des enregistrements Personnes / Organisations où la table imbriquée Rôles contient Artiste, findTerms nécessite simplement :

   $search->add('NamRoles_tab', 'Artist');

   D’autre part, la clause TexQL équivalente est :

   exists(NamRoles_tab where NamRoles contains 'Artist')

   Le TexQL pour les tables doublement imbriquées est encore plus complexe.

2. Plus important encore, findTerms est plus sûr.

   Avec findTerms, un ensemble de termes est soumis au serveur qui construit ensuite la clause TexQL where. Il est ainsi beaucoup plus facile pour le serveur de vérifier les termes susceptibles de contenir des attaques de type injection SQL et de les éviter. Si votre code construit une clause where à partir des données saisies par l’utilisateur afin qu’elle puisse être exécutée à l’aide de findWhere, il est beaucoup plus difficile, voire impossible, pour le serveur de vérifier et d’éviter l’injection SQL. La responsabilité de la vérification de l’injection SQL vous incombe.

Toutes les méthodes find renvoient le nombre de correspondances trouvées par la recherche. Pour findKey et findKeys, ce nombre est toujours le nombre exact de correspondances trouvées. Le nombre renvoyé par findTerms et findWhere est à considérer comme une estimation. Cette estimation est presque toujours correcte, mais en raison de la nature de l’indexation utilisée par le moteur de données du serveur (Texpress), le nombre peut parfois être une surestimation du nombre réel de correspondances. Ce nombre est similaire au nombre estimé de résultats retournés par une recherche Google.