Rechercher un module

La méthode FindKey recherche un seul enregistrement par sa clé. La clé est un entier long (c’est-à-dire long en C#, Long en VB).

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

C#

using IMu;

// ⋯

Module parties = new Module("eparties", session);

long hits = parties.FindKey(42);

VB

Dim parties = New IMu.Module("eparties", session)

Dim 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’un tableau d’entiers longs.

C#

using IMu;

// ⋯

Module parties = new Module("eparties", session);

long[] keys = { 52, 42, 17 };

long hits = parties.FindKeys(keys);

VB

Dim parties = New IMu.Module("eparties", session)

Dim keys() As Long = {52, 42, 17}

Dim hits = parties.FindKeys(keys)

ou en tant que List :

C#

Module parties = new Module("eparties", session);

List<long> keys = new List<long>();

keys.Add(52);

keys.Add(42);

keys.Add(17);

long hits = parties.FindKeys(keys);

VB

Dim parties = New IMu.Module("eparties", session)

Dim keys New List(Of Long)

keys.Add(1)

keys.Add(2)

keys.Add(3)

Dim 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 Terms. Une fois qu’un objet Terms a été créé, ajoutez-y des termes spécifiques (à l’aide de la méthode Add), puis passez l’objet 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 :

C#

Terms search = new Terms();

search.Add("NamFirst", "John");

search.Add("NamLast", "Smith");

// ⋯

long hits = parties.FindTerms(search);

VB

Dim search = New Terms

search.Add("NamFirst", "John")

search.Add("NamLast", "Smith")

' ⋯

Dim 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é :

   C#

   Terms search = new Terms();

   search.Add("NamLast", "Smith");

   VB

   Dim search = New Terms

   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 :

   C#

   Terms search = new Terms();

   search.Add("AdmDateInserted", "Avr 4 2011");

   VB

   Dim search = New Terms

   search.Add("AdmDateInserted", "Avr 4 2011")

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

   C#

   Terms search = new Terms();

   search.Add("AdmDateInserted", "Avr 4 2011", "<");

   VB

   Dim search = New Terms

   search.Add("AdmDateInserted", "Avr 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 Terms peut être créé comme suit :

   C#

   Terms search = new Terms();

   search.Add("NamFirst", "John");

   search.Add("NamLast", "Smith");

   VB

   Dim search = New Terms

   search.Add("NamFirst", "John")

   search.Add("NamLast", "Smith")

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

   C#

   Terms search = new Terms(TermsKind.OR);

   search.Add("NamFirst", "John");

   search.Add("NamLast", "Smith");

   VB

   Dim search = New Terms(TermsKind.OR)

   search.Add("NamFirst", "John")

   search.Add("NamLast", "Smith")

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

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 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 au jeu de résultats correspondant inséré avant le 4 avril 2011 ou le 1er mai 2011, précisez :

   C#

   Terms search = new Terms();

   search.Add("NamFirst", "John");

   search.Add("NamLast", "Smith");

   Terms dates = search.AddOr();

   dates.Add("AdmDateInserted", "Avr 4 2011", "<");

   dates.Add("AdmDateInserted", "Mai 1 2011");

   VB

   Dim search = New Terms

   search.Add("NamFirst", "John")

   search.Add("NamLast", "Smith")

   Dim dates = search.AddOr()

   dates.Add("AdmDateInserted", "Avr 4 2011", "<")

   dates.Add("AdmDateInserted", "Mai 1 2011")

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

   C#

   Module parties = new Module("eparties", session);

   Terms search = new Terms();

   search.Add("NamLast", "Smith");

   long hits = parties.FindTerms(search);

   VB

   Dim parties = New IMu.Module("eparties", session)

   Dim search = New Terms

   search.Add("NamFirst", "John")

   Dim 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 :

   C#

   string keyword = "⋯";

   // ⋯

   Terms search = new Terms(TermsKind.OR);

   search.Add("SummaryData", keyword);

   search.Add("CatSubjects_tab", keyword);

   search.Add("NotNotes", keyword);

   VB

   Dim keyword As String = "⋯"

   ' ⋯

   Dim search = New Terms(TermsKind.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 :

   C#

   string keyword = "⋯";

   // ⋯

   Module catalogue = new Module("ecatalogue", session);

   string[] columns =

   {

   "SummaryData",

   "CatSubjects_tab",

   "NotNotes"

   };

   catalogue.AddSearchAlias("keywords", columns);

   // ⋯

   Terms search = new Terms();

   search.Add("keywords", keyword);

   catalogue.FindTerms(search);

   VB

   Dim keyword As String = "⋯"

   ' ⋯

   Dim catalogue = New IMu.Module("ecatalogue", session)

   Dim columns() As String =

   {

   "SummaryData",

   "NamRoles_tab",

   "NotNotes"

   }

   catalogue.AddSearchAlias("keywords", columns)

   ' ⋯

   Dim search = New Terms

   search.Add("keywords", keyword)

   catalogue.FindTerms(search)

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

   C#

   string keyword = "⋯";

   // ⋯

   Module catalogue = new Module("ecatalogue", session);

   string columns = "SummaryData;CatSubjects_tab;NotNotes";

   catalogue.AddSearchAlias("keywords", columns);

   // ⋯

   Terms search = new Terms();

   search.Add("keywords", keyword);

   catalogue.FindTerms(search);

   VB

   Dim keyword As String = "⋯"

   ' ⋯

   Dim catalogue = Neww IMu.Module("ecatalogue", session)

   Dim columns = "SummaryData;CatSubjects_tab;NotNotes"

   catalogue.AddSearchAlias("keywords", columns)

   ' ⋯

   Dim search = New Terms

   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, utilisez la classe IMu Map pour créer un tableau associatif de noms et de colonnes et appelez la méthode AddSearchAliases :

   C#

   Map aliases = new Map();

   aliases.Add("keywords", "SummaryData;CatSubjects_tab;NotNotes");

   aliases.Add("title", "SummaryData;TitMainTitle");

   catalogue.AddSearchAliases(aliases);

   VB

   Dim aliases = New Map

   aliases.Add("keywords", "SummaryData;CatSubjects_tab;NotNotes")

   aliases.Add("title", "SummaryData;TitMainTitle")

   catalogue.AddSearchAliases(aliases)

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

C#

Module parties = new Module("eparties", session);

string where = "NamLast contains 'Smith'";

long hits = parties.FindWhere(where);

VB

Dim parties = New IMu.Module("eparties", session)

Dim where = "NamLast contains 'Smith'"

Dim 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 Artist, 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.