Tweak rank/relevance algorithm
[pazpar2-moved-to-github.git] / doc / pazpar2_conf.xml
index f41070c..454cc02 100644 (file)
             Specifies that this element is to be used to
             help rank 
             records against the user's query (when ranking is
-            requested). The value is an integer, used as a
+            requested). 
+            The valus is of the form 
+            <literallayout>
+             M [F N]
+            </literallayout>
+            where M is an integer, used as a
             multiplier against the basic TF*IDF score. A value of
-            1 is the base, higher values give additional
-            weight to 
+            1 is the base, higher values give additional weight to
             elements of this type. The default is '0', which
             excludes this element from the rank calculation.
            </para>
+           <para>
+            F is a CCL field and N is the multipler for terms
+            that matches those part of the CCL field in search.
+            The F+N combo allows the system to use a different
+            multipler for a certain field. For example, a rank value of
+            "<literal>1 au 3</literal>" gives a multipler of 3 for
+            all terms part of the au(thor) terms and 1 for everything else.
+           </para>
+           <para>
+            For Pazpar2 1.6.13 and later, the rank may also defined
+            "per-document", by the normalization stylesheet. 
+           </para>
+           <para>
+            The per field rank was introduced in Pazpar2 1.6.15. Earlier
+            releases only allowed a rank value M (simple integer).
+           </para>
           </listitem>
          </varlistentry>
          
          </varlistentry>
          
          <varlistentry>
+          <term id="metadata_limitmap">limitmap</term>
+          <listitem>
+           <para>
+            Specifies a default limitmap for this field. This is to avoid mass 
+            configuring of targets. However it is important to review/do this on a per
+            target since it is usually target-specific. See limitmap for format. 
+           </para>
+          </listitem>
+         </varlistentry>
+         
+         <varlistentry>
+          <term id="metadata_facetmap">facetmap</term>
+          <listitem>
+           <para>
+            Specifies a default facetmap for this field. This is to avoid mass 
+            configuring of targets. However it is important to review/do this on a per
+            target since it is usually target-specific. See facetmap for format. 
+           </para>
+          </listitem>
+         </varlistentry>
+         
+         <varlistentry>
           <term>setting</term>
           <listitem>
            <para>
         </para>
        </listitem>
        </varlistentry>
-       
+
+       <varlistentry>
+       <term>ccldirective</term>
+       <listitem>
+        <para>
+         Customizes the CCL parsing (interpretation of query parameter
+         in search).
+         The name and value of the CCL directive is gigen by attributes
+         'name' and 'value' respectively. Refer to possible list of names
+         in the
+         <ulink 
+             url="http://www.indexdata.com/yaz/doc/tools.html#ccl.directives.table">
+          YAZ manual
+          </ulink>.
+        </para>
+       </listitem>
+       </varlistentry>
+
+       <varlistentry>
+       <term>rank</term>
+       <listitem>
+        <para>
+         Customizes the ranking (relevance) algorithm.
+         Attribute 'cluster' is a boolean
+         that controls whether Pazpar2 should boost ranking for merged
+         records. Is 'yes' by default. A value of 'no' will make
+         Pazpar2 avergage ranking of each record in a cluster.
+        </para>
+        <para>
+         This configuration was added in pazpar2 1.6.18.
+        </para>
+       </listitem>
+       </varlistentry>
+
+<!--       
+       <varlistentry>
+       <term>set</term>
+       <listitem>
+        <para>
+         Specifies a variable that will be inherited by all targets defined in settings
+         <screen>
+          &lt;set name="test" value="en"..&lt;set>
+         </screen>
+        </para>
+       </listitem>
+       </varlistentry>
+-->   
        <varlistentry>
        <term>settings</term>
        <listitem>
              type="year" merge="range" termlist="yes"/>
    <metadata name="author" brief="yes" termlist="yes"
              merge="longest" rank="2"/>
-   <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
+   <metadata name="subject" merge="unique" termlist="yes" rank="3" limitmap="local:"/>
    <metadata name="url" merge="unique"/>
    <icu_chain id="relevance" locale="el">
     <transform rule="[:Control:] Any-Remove"/>
      </listitem>
     </varlistentry>
     <varlistentry>
+     <term>pz:presentchunk</term>
+     <listitem>
+      <para>
+       Controls the chunk size in present requests. Pazpar2 will 
+       make (maxrecs / chunk) request(s). The default is 20.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
      <term>pz:id</term>
      <listitem>
       <para>
      <listitem>
       <para>
        This setting enables
-       <ulink url="&url.sru;">SRU</ulink>/<ulink url="&url.solr;">SOLR</ulink>
+       <ulink url="&url.sru;">SRU</ulink>/<ulink url="&url.solr;">Solr</ulink>
        support.
        It has four possible settings.
        'get', enables SRU access through GET requests. 'post' enables SRU/POST
        the protocol.
       </para>
       <para>
-       A value of 'solr' anables SOLR client support. This is supported
+       A value of 'solr' enables Solr client support. This is supported
        for Pazpar version 1.5.0 and later.
       </para>
      </listitem>
       <para>
        This allows SRU version to be specified. If unset Pazpar2
        will the default of YAZ (currently 1.2). Should be set
-       to 1.1 or 1.2. For SOLR, the current supported/tested version is 1.4
+       to 1.1 or 1.2. For Solr, the current supported/tested version is 1.4 and 3.x.
       </para>
      </listitem>
     </varlistentry>
      <listitem>
       <para>
        Allows you to specify an arbitrary PQF query language substring.
-       The provided string is prefixed the user's query after it has been
+       The provided string is prefixed to the user's query after it has been
        normalized to PQF internally in pazpar2.
        This allows you to attach complex 'filters' to queries for a given
        target, sometimes necessary to select sub-catalogs
        <literal>@and @attr 1=30 @attr 2=3 %Y %%</literal>
        would search for current year combined with the original PQF (%%).
       </para>
+      <para>
+       This setting can also be used as more general alternative to
+       pz:pqf_prefix -- a way of embedding the submitted query
+       anywhere in the string rather than appending it to prefix.  For
+       example, if it is desired to omit all records satisfying the
+       query <literal>@attr 1=pica.bib 0007</literal> then this
+       subquery can be combined with the submitted query as the second
+       argument of <literal>@andnot</literal> by using the
+       pz:pqf_strftime value <literal>@not %% @attr 1=pica.bib
+       0007</literal>.
+      </para>
      </listitem>
     </varlistentry>
     
       </para>
      </listitem>
     </varlistentry>
-
     <varlistentry>
      <term>pz:block_timeout</term>
      <listitem>
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term>pz:termlist_term_count</term>
+     <listitem>
+      <para>
+       Specifies number of facet terms to be requested from the target. 
+       The default is unspecified e.g. server-decided. Also see pz:facetmap.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>pz:termlist_term_factor</term>
+     <listitem>
+      <para>
+       Specifies whether to use a factor for pazpar2 generated facets (1) or not (0). 
+       When mixing locallly generated (by the downloaded (pz:maxrecs) samples) 
+       facet with native (target-generated) facets, the later will dominated the dominate the facet list
+       since they are generated based on the complete result set. 
+       By scaling up the facet count using the ratio between total hit count and the sample size, 
+       the total facet count can be approximated and thus better compared with native facets. 
+       This is not enabled by default.
+      </para>
+     </listitem>
+    </varlistentry>
 
     <varlistentry>
      <term>pz:facetmap:<replaceable>name</replaceable></term>
       </para>
       <note>
        <para>
-       At this point only SOLR targets have been tested with this
+       At this point only Solr targets have been tested with this
        facility.
        </para>
       </note>
        an existing CCL field, a raw PQF string or a local limit. Leading string
        determines type; either <literal>ccl:</literal> for CCL field, 
        <literal>rpn:</literal> for PQF/RPN, or <literal>local:</literal>
-       for filtering in Pazpar2.
+       for filtering in Pazpar2. The local filtering may be followed
+       by a field a metadata field (default is to use the name of the 
+       limitmap itself).
       </para>
       <note>
        <para>