Différences

Ci-dessous, les différences entre deux révisions de la page.

--- serveurscrutari:json:qsyntax [2013/04/17 15:20] – créée vincent
+++ serveurscrutari:json:qsyntax [2015/03/24 23:46] (Version actuelle) – [Cas particulier de la recherche « tous »] vincent
@@ Ligne 1: / Ligne 1: @@
 ====== Syntaxe d'une recherche ======
+Une recherche est définie par la valeur du paramètre //q//, ce paramètre est complété par le paramètre //q-mode// qui indique le mode de traitement à appliquer à la chaine définie par //q//.
+//q-mode// a trois valeurs possibles :
+  * //intersection// (valeur par défaut si //q-mode// n'est pas défini)
+  * //union//
+  * //operation//
+//intersection// et //union// sont deux variantes de la recherche simple. //operation// correspond à la recherche avancée.
+===== Recherche simple =====
+Dans la recherche simple, le paramètre //q// est censé contenir les mots de la recherche séparé par un espace. On utilise des guillemets droits pour indiquer une recherche sur un groupe de mots qui se succèdent.
+Les troncatures (recherche sur les mots comprenant une partie du terme) sont indiquées avec un astérisque (y compris pour les termes entre guillemets). L'astérisque en début de terme indique que l'on recherche les mots finissant par le terme, en fin de terme que l'on recherche les mots commençant et aux deux bouts que l'on recherche les mots contenant le terme n'importe où. Par défaut, un astérisque est automatiquement rajouté en fin de terme pour les termes qui ne sont pas entre guillemets, ce comportement pouvant être modifié par la valeur du paramètre //wildchar//.
+Si //q-mode// a la valeur //intersection// (ou s'il n'est pas indiqué), on a une recherche « ET » : on recherche les fiches qui contiennent tous les mots de la recherche. Si //q-mode// a la valeur //union//, on a une recherche « OU » : on recherche les fiches qui contiennent un des mots de la recherche.
+Cela donne les exemples suivants :
+<code javascript>
+q=gouv //Recherche des mots commençant par gouv
+q=*logie //Recherche des mots terminant par logie
+q=*eco* //Recherche des mots contenant eco
+q="bio" //recherche du mot bio (les guillemets évitent la troncature à droite automatique
+q="agriculture biologique" //Recherche de la séquence de deux mots consécutifs "agriculture et biologique"
+q="gouv* pub*" //Recherche d'une séquence d'un mot commençant par gouv suivi d'un mot commençant par pub
+</code>
+Avec //q-mode// = //intersection//
+<code javascript>
+q=magasin alimentation //(Mots commençant par magasin) ET (Mots commençant par alimentation)
+q=environnement "agricult* bio*" // (Mots commençant par environnement) ET (séquence d'un mot commençant par agricult suivi d'un mot commençant par bio)
+</code>
+Avec //q-mode// = //union//
+<code javascript>
+q=politique gouvernance *publ*//(Mots commençant par politique) OU (Mots commençant par gouvernence) OU (Mots contentant publ)
+</code>
+Une précision : les caractères autres que des chiffres et des lettres sont ignorés et traités comme des séparateurs de mots.
+===== Recherche avancée =====
+La recherche avancée est construit sur la même logique que celle de la combinaison filtres (voir [[serveurscrutari:json:filtersyntax|Syntaxe des filtres]]) avec les trois opérateurs logiques suivants :
+  * && : Et
+  * || : Ou
+  * ! : Non
+On utilise les parenthèses pour les regroupements. Un mot doit être composé uniquement de chiffres et de lettres. La présence d'un caractère spécial entraine une erreur. On utilise des guillemets pour indiquer une séquence de mots séparés par un espace.
+Les règles de troncature sont les mêmes que celles de la recherche simple (concature à droite automatique, astérisques
+Cela donne les exemples suivants :
+<code javascript>
+q= agriculture && !biologique //cherche les fiches contenant un mot commençant par agriculture et ne contenant pas de mot commençant par biologique
+q= agriculture && !(biologique || pays) //cherche les fiches contenant un mot commençant par agriculture et ne contenant ni mot commençant par biologique, ni mot commençant par pays
+q= !*dev* //Toutes les fiches qui ne contiennent pas un mot contenant dev
+q= ("agriculture* bioloqique*" || "agriculture* paysanne*") && !Larzac // fiches contenant agriculture biologique ou agriculture paysanne et ne parlant pas du Larzac
+</code>
+==== Limitation de l'étendue d'une recherche ====
+Il est possible de limiter la recherche pour un mot particulier en le préfixant avec un nom de champ. Les préfixes possibles sont :
+  * //titre:// dans les titres uniquement
+  * //soustitre:// dans les sous-titres uniquement
+  * //motcle:// dans les mots-clés uniquement
+  * //supplement:// dans les champs « supplémentaires » (les champs complémentaires et les attributs)
+  * tout nom d'attribut défini par le serveur (par exemple, //sct:authors://)
+Cela donne :
+<code javascript>
+q=sct:authors:Daudet //Recherche sur l'auteur Daudet
+q= titre:pol && !sct:authors:Dupont //fiche avec un mot commençant par pol dans le titre et dont l'auteur 'nest pas Dupont
+</code>
+Plusieurs préfixes peuvent être indiqués en les séparant par des virgules (bien faire attention à ne pas mettre d'espace). Par exemple :
+<code javascript>
+q=titre,soustitre:développement //fiches contenant « développement » dans le titre ou le sous-titre
+</code>
+Il est possible également d'exclure un préfixe en le précédant du point d'exclamation //!//. Cela peut être utile pour exclure un attribut, par exemple :
+<code javascript>
+q=supplement,!sct:authors:Dupont //cherche Dupont dans tous les champs supplémentaires sauf l'attribut sct:authors
+</code>
+Dans des cas rares, l'utilisation du caractère //!// en début des préfixes entre en conflit avec l'utilisation de //!// comme opérateur de négation. Pour l'éviter, on commencera les préfixes par une virgule //,//. L'exemple suivant montre les différences :
+<code javascript>
+q=!sct:authors:Dupont //cherche les références qui n'ont pas Dupont dans l'attribut sct:authors
+q=,!sct:authors:Dupont //cherche Dupont dans tous les champs sauf l'attribut sct:authors
+</code>
+Les préfixes (sauf les noms d'attributs) sont internationalisés pour faciliter leur utilisation. Par exemple, un utilisateur hispanophone pourra utiliser //titulo:// plutôt que //titre//. Cette internationalisation est pour l'instant disponible pour l'espagnol. Les équivalences sont les suivantes :
+  * //titre// : //titulo//
+  * //soustitre// : //subtitulo//
+  * //motcle// : //palabraclave//
+  *  //supplement// : //suplemento//
+==== Cas particulier de la recherche « tous » ====
+Il est possible en recherche avancée d'indiquer pour la valeur de //q// le simple caractère //*// : cela signifie que l'on veut toutes les fiches répondant aux filtres initiaux (s'il n'y a pas de filtres initiaux, toutes les fiches de la base sont renvoyées). Le résultat est équivalent à celui renvoyé par la requête [[serveurscrutari:json:type_fiche|type=fiche]] avec les mêmes filtres, à ceci près que les résultats seront organisés de la même façon qu'une recherche normale avec //q// valide (en particulier, le format JSON reçu sera le même).
+//q=*// n'est opérationnel qu'en recherche avancée ; dans les recherches simples et composées, c'est considérée comme une erreur de syntaxe.
+===== Recherche composée =====
+Une recherche composée permet de combiner la simplicité de la syntaxe d'une recherche simple avec les possibilités de limitation de l'étendue d'une recherche offertes dans la recherche avancée. La recherche composée permet de concevoir des formulaires de recherche avec des champs de saisie différents pour les différents champs (par exemple, un champ pour les titres et un champ pour les auteurs). Un exemple de recherche composée en action peut être vue sur la page de test suivante : http://test.scrutari.net/index-multi.php.
+La recherche composée est une exception au caractère obligatoire du paramètre //q//. Il peut toujours être utilisé mais il est complété voire complété par une série de paramètres commençant par //q_//, les caractères après //q_// constituant le nom de la sous-recherche.
+Par exemple, le formulaire de la page  http://test.scrutari.net/index-multi.php a quatre champs de saisie qui ont les noms suivants :
+<code javascript>
+q_1 // Champ « Titre, sous-titre »
+q_2 // Champ « Auteurs »
+q_3 // Champ « Mots-clés »
+q_4 // champ « Autres champs »
+</code>
+Dans l'exemple, les noms sont des numéros mais cela n'a rien d'obligatoire. On peut avoir un paramètre portant le nom //q_entete// par exemple.
+Pour que la recherche composée soit intéressante, il faut préciser pour chaque paramètre son étendue. Cela se fait avec un autre paramètre //q-scope_// suivi du nom. Ce qui donne dans notre exemple :
+<code javascript>
+q_1 // Champ « Titre, sous-titre »
+q-scope_1=titre,soustitre
+q_2 // Champ « Auteurs »
+q-scope_2=sct:authors
+q_3 // Champ « Mots-clés »
+q-scope_3=motcle
+q_4 // champ « Autres champs »
+q-scope_4=supplement,!sct:authors // !sct:authors sert à exclure l'attribut sct:authors des champs supplémentaires
+</code>
+Le paramètre //q-mode// est toujours utilisé mais il ne doit pas avoir la valeur //operation//. Il indique d'une part la relation entre les différents sous-champs et, d'autre, part, la relation par défaut à l'intérieur d'un champ. La relation à l'intérieur d'un champ peut être précisée avec le paramètre //q-mode_// suivi du nom.
+Considérons l'exemple suivant :
+<code javascript>
+q_mode=intersection
+q_entete=économie* politique*
+q-scope_entete=titre,soustitre
+q_auteurs=Dupont Martin
+q-scope_auteurs=sct:authors
+q-mode_auteurs=union
+</code>
+Cet exemple se lit de la manière suivante : recherche des fiches avec « économie* » ET « politique* »  (//q_entete=économie* politique*//,  //q_mode=intersection//) dans le titre ou le sous-titre (//q-scope_entete=titre,soustitre//) ET (//q-mode=intersection//) avec « Dupont » OU « Martin » (//q_auteursDupont Martin//,  //q-mode_auteurs=union//) comme auteurs (//q-scope_auteurs=sct:authors//)
+Cette recherche est équivalente à la recherche suivante exprimée dans la syntaxe avancée :
+<code javascript>
+(titre,soustitre:économie* && titre,soustitre:politique*) && (sct:authors:Dupont || sct:authors:Martin)
+</code>