+ The attribute-set <literal>exp-1</literal> consists of a single
+ <literal>use attribute (type 1)</literal>.
+ </para>
+ <para>
+ In addition, the non-Use
+ <literal>bib-1</literal> attributes, that is, the types
+ <literal>Relation</literal>, <literal>Position</literal>,
+ <literal>Structure</literal>, <literal>Truncation</literal>,
+ and <literal>Completeness</literal> are imported from
+ the <literal>bib-1</literal> attribute set, and may be used
+ within any explain query.
+ </para>
+
+ <sect3 id="querymodel-exp1-use">
+ <title>Use Attributes (type = 1)</title>
+ <para>
+ The following Explain search atributes are supported:
+ <literal>ExplainCategory</literal> (@attr 1=1),
+ <literal>DatabaseName</literal> (@attr 1=3),
+ <literal>DateAdded</literal> (@attr 1=9),
+ <literal>DateChanged</literal>(@attr 1=10).
+ </para>
+ <para>
+ A search in the use attribute <literal>ExplainCategory</literal>
+ supports only these predefined values:
+ <literal>CategoryList</literal>, <literal>TargetInfo</literal>,
+ <literal>DatabaseInfo</literal>, <literal>AttributeDetails</literal>.
+ </para>
+ <para>
+ See <filename>tab/explain.att</filename> and the
+ <ulink url="&url.z39.50;">Z39.50</ulink> standard
+ for more information.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Explain searches with yaz-client</title>
+ <para>
+ Classic Explain only defines retrieval of Explain information
+ via ASN.1. Pratically no Z39.50 clients supports this. Fortunately
+ they don't have to - Zebra allows retrieval of this information
+ in other formats:
+ <literal>SUTRS</literal>, <literal>XML</literal>,
+ <literal>GRS-1</literal> and <literal>ASN.1</literal> Explain.
+ </para>
+
+ <para>
+ List supported categories to find out which explain commands are
+ supported:
+ <screen>
+ Z> base IR-Explain-1
+ Z> find @attr exp1 1=1 categorylist
+ Z> form sutrs
+ Z> show 1+2
+ </screen>
+ </para>
+
+ <para>
+ Get target info, that is, investigate which databases exist at
+ this server endpoint:
+ <screen>
+ Z> base IR-Explain-1
+ Z> find @attr exp1 1=1 targetinfo
+ Z> form xml
+ Z> show 1+1
+ Z> form grs-1
+ Z> show 1+1
+ Z> form sutrs
+ Z> show 1+1
+ </screen>
+ </para>
+
+ <para>
+ List all supported databases, the number of hits
+ is the number of databases found, which most commonly are the
+ following two:
+ the <literal>Default</literal> and the
+ <literal>IR-Explain-1</literal> databases.
+ <screen>
+ Z> base IR-Explain-1
+ Z> find @attr exp1 1=1 databaseinfo
+ Z> form sutrs
+ Z> show 1+2
+ </screen>
+ </para>
+
+ <para>
+ Get database info record for database <literal>Default</literal>.
+ <screen>
+ Z> base IR-Explain-1
+ Z> find @and @attr exp1 1=1 databaseinfo @attr exp1 1=3 Default
+ </screen>
+ Identical query with explicitly specified attribute set:
+ <screen>
+ Z> base IR-Explain-1
+ Z> find @attrset exp1 @and @attr 1=1 databaseinfo @attr 1=3 Default
+ </screen>
+ </para>
+
+ <para>
+ Get attribute details record for database
+ <literal>Default</literal>.
+ This query is very useful to study the internal Zebra indexes.
+ If records have been indexed using the <literal>alvis</literal>
+ XSLT filter, the string representation names of the known indexes can be
+ found.
+ <screen>
+ Z> base IR-Explain-1
+ Z> find @and @attr exp1 1=1 attributedetails @attr exp1 1=3 Default
+ </screen>
+ Identical query with explicitly specified attribute set:
+ <screen>
+ Z> base IR-Explain-1
+ Z> find @attrset exp1 @and @attr 1=1 attributedetails @attr 1=3 Default
+ </screen>
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="querymodel-bib1">
+ <title>Bib1 Attribute Set</title>
+ <para>
+ Most of the information contained in this section is an excerpt of
+ the <literal>ATTRIBUTE SET BIB-1 (Z39.50-1995)
+ SEMANTICS</literal>,
+ found at <ulink url="&url.z39.50.attset.bib1.1995;">. The BIB-1
+ Attribute Set Semantics</ulink> from 1995, also in an updated
+ <ulink url="&url.z39.50.attset.bib1;">Bib-1
+ Attribute Set</ulink>
+ version from 2003. Index Data is not the copyright holder of this
+ information, except for the configuration details, the listing of
+ Zebra's capabilities, and the example queries.
+ </para>
+
+
+ <sect3 id="querymodel-bib1-use">
+ <title>Use Attributes (type 1)</title>
+
+ <para>
+ A use attribute specifies an access point for any atomic query.
+ These acess points are highly dependent on the attribute set used
+ in the query, and are user configurable using the following
+ default configuration files:
+ <filename>tab/bib1.att</filename>,
+ <filename>tab/dan1.att</filename>,
+ <filename>tab/explain.att</filename>, and
+ <filename>tab/gils.att</filename>.
+ New attribute sets can be added by adding new
+ <filename>tab/*.att</filename> configuration files, which need to
+ be sourced in the main configuration <filename>zebra.cfg</filename>.
+ </para>
+
+ <para>
+ In addition, Zebra allows the acess of
+ <emphasis>internal index names</emphasis> and <emphasis>dynamic
+ XPath</emphasis> as use attributes; see
+ <xref linkend="querymodel-use-string"/> and
+ <xref linkend="querymodel-use-xpath"/>.
+ </para>
+
+ <para>
+ Phrase search for <emphasis>information retrieval</emphasis> in
+ the title-register, scanning the same register afterwards:
+ <screen>
+ Z> find @attr 1=4 "information retrieval"
+ Z> scan @attr 1=4 information
+ </screen>
+ </para>
+ </sect3>
+
+ </sect2>
+
+
+ <sect2 id="querymodel-bib1-nonuse">
+ <title>Zebra general Bib1 Non-Use Attributes (type 2-6)</title>
+
+ <sect3 id="querymodel-bib1-relation">
+ <title>Relation Attributes (type 2)</title>
+
+ <para>
+ Relation attributes describe the relationship of the access
+ point (left side
+ of the relation) to the search term as qualified by the attributes (right
+ side of the relation), e.g., Date-publication <= 1975.
+ </para>
+
+ <table id="querymodel-bib1-relation-table"
+ frame="all" rowsep="1" colsep="1" align="center">
+
+ <caption>Relation Attributes (type 2)</caption>
+ <thead>
+ <tr>
+ <td>Relation</td>
+ <td>Value</td>
+ <td>Notes</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td> Less than</td>
+ <td>1</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Less than or equal</td>
+ <td>2</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Equal</td>
+ <td>3</td>
+ <td>default</td>
+ </tr>
+ <tr>
+ <td>Greater or equal</td>
+ <td>4</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Greater than</td>
+ <td>5</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Not equal</td>
+ <td>6</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Phonetic</td>
+ <td>100</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Stem</td>
+ <td>101</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Relevance</td>
+ <td>102</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>AlwaysMatches</td>
+ <td>103</td>
+ <td>supported</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <para>
+ The relation attributes
+ <literal>1-5</literal> are supported and work exactly as
+ expected.
+ All ordering operations are based on a lexicographical ordering,
+ <emphasis>expect</emphasis> when the
+ <literal>structure attribute numeric (109)</literal> is used. In
+ this case, ordering is numerical. See
+ <xref linkend="querymodel-bib1-structure"/>.
+ <screen>
+ Z> find @attr 1=Title @attr 2=1 music
+ ...
+ Number of hits: 11745, setno 1
+ ...
+ Z> find @attr 1=Title @attr 2=2 music
+ ...
+ Number of hits: 11771, setno 2
+ ...
+ Z> find @attr 1=Title @attr 2=3 music
+ ...
+ Number of hits: 532, setno 3
+ ...
+ Z> find @attr 1=Title @attr 2=4 music
+ ...
+ Number of hits: 11463, setno 4
+ ...
+ Z> find @attr 1=Title @attr 2=5 music
+ ...
+ Number of hits: 11419, setno 5
+ </screen>
+ </para>
+
+ <para>
+ The relation attribute
+ <literal>Relevance (102)</literal> is supported, see
+ <xref linkend="administration-ranking"/> for full information.
+ </para>
+
+ <para>
+ Ranked search for <emphasis>information retrieval</emphasis> in
+ the title-register:
+ <screen>
+ Z> find @attr 1=4 @attr 2=102 "information retrieval"
+ </screen>
+ </para>
+
+ <para>
+ The relation attribute
+ <literal>AlwaysMatches (103)</literal> is in the default
+ configuration
+ supported in conjecture with structure attribute
+ <literal>Phrase (1)</literal> (which may be omitted by
+ default).
+ It can be configured to work with other structure attributes,
+ see the configuration file
+ <filename>tab/default.idx</filename> and
+ <xref linkend="querymodel-pqf-apt-mapping"/>.
+ </para>
+ <para>
+ <literal>AlwaysMatches (103)</literal> is a
+ great way to discover how many documents have been indexed in a
+ given field. The search term is ignored, but needed for correct
+ PQF syntax. An empty search term may be supplied.
+ <screen>
+ Z> find @attr 1=Title @attr 2=103 ""
+ Z> find @attr 1=Title @attr 2=103 @attr 4=1 ""
+ </screen>
+ </para>
+
+
+ </sect3>
+
+ <sect3 id="querymodel-bib1-position">
+ <title>Position Attributes (type 3)</title>
+
+ <para>
+ The position attribute specifies the location of the search term
+ within the field or subfield in which it appears.
+ </para>
+
+ <table id="querymodel-bib1-position-table"
+ frame="all" rowsep="1" colsep="1" align="center">
+
+ <caption>Position Attributes (type 3)</caption>
+ <thead>
+ <tr>
+ <td>Position</td>
+ <td>Value</td>
+ <td>Notes</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>First in field </td>
+ <td>1</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>First in subfield</td>
+ <td>2</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Any position in field</td>
+ <td>3</td>
+ <td>default</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <para>
+ The position attribute values <literal>first in field (1)</literal>,
+ and <literal>first in subfield(2)</literal> are unsupported.
+ Using them does not trigger an error, but silent defaults to
+ <literal>any position in field (3)</literal>.
+ <!-- It should -->
+ </para>
+ </sect3>
+
+ <sect3 id="querymodel-bib1-structure">
+ <title>Structure Attributes (type 4)</title>
+
+ <para>
+ The structure attribute specifies the type of search
+ term. This causes the search to be mapped on
+ different Zebra internal indexes, which must have been defined
+ at index time.
+ </para>
+
+ <para>
+ The possible values of the
+ <literal>structure attribute (type 4)</literal> can be defined
+ using the configuration file <filename>
+ tab/default.idx</filename>.
+ The default configuration is summerized in this table.
+ </para>
+
+ <table id="querymodel-bib1-structure-table"
+ frame="all" rowsep="1" colsep="1" align="center">
+
+ <caption>Structure Attributes (type 4)</caption>
+ <thead>
+ <tr>
+ <td>Structure</td>
+ <td>Value</td>
+ <td>Notes</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Phrase </td>
+ <td>1</td>
+ <td>default</td>
+ </tr>
+ <tr>
+ <td>Word</td>
+ <td>2</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Key</td>
+ <td>3</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Year</td>
+ <td>4</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Date (normalized)</td>
+ <td>5</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Word list</td>
+ <td>6</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Date (un-normalized)</td>
+ <td>100</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Name (normalized) </td>
+ <td>101</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Name (un-normalized) </td>
+ <td>102</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Structure</td>
+ <td>103</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Urx</td>
+ <td>104</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Free-form-text</td>
+ <td>105</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Document-text</td>
+ <td>106</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Local-number</td>
+ <td>107</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>String</td>
+ <td>108</td>
+ <td>unsupported</td>
+ </tr>
+ <tr>
+ <td>Numeric string</td>
+ <td>109</td>
+ <td>supported</td>
+ </tr>
+ </tbody>
+ </table>
+
+
+ <para>
+ The structure attribute values
+ <literal>Word list (6)</literal>
+ is supported, and maps to the boolean <literal>AND</literal>
+ combination of words supplied. The word list is useful when
+ google-like bag-of-word queries need to be translated from a GUI
+ query language to PQF. For example, the following queries
+ are equivalent:
+ <screen>
+ Z> find @attr 1=Title @attr 4=6 "mozart amadeus"
+ Z> find @attr 1=Title @and mozart amadeus
+ </screen>
+ </para>
+
+ <para>
+ The structure attribute value
+ <literal>Free-form-text (105)</literal> and
+ <literal>Document-text (106)</literal>
+ are supported, and map both to the boolean <literal>OR</literal>
+ combination of words supplied. The following queries
+ are equivalent:
+ <screen>
+ Z> find @attr 1=Body-of-text @attr 4=105 "bach salieri teleman"
+ Z> find @attr 1=Body-of-text @attr 4=106 "bach salieri teleman"
+ Z> find @attr 1=Body-of-text @or bach @or salieri teleman
+ </screen>
+ This <literal>OR</literal> list of terms is very usefull in
+ combination with relevance ranking:
+ <screen>
+ Z> find @attr 1=Body-of-text @attr 2=102 @attr 4=105 "bach salieri teleman"
+ </screen>
+ </para>
+
+ <para>
+ The structure attribute value
+ <literal>Local number (107)</literal>
+ is supported, and maps always to the Zebra internal document ID,
+ irrespectively which use attribute is specified. The following queries
+ have exactly the same unique record in the hit set:
+ <screen>
+ Z> find @attr 4=107 10
+ Z> find @attr 1=4 @attr 4=107 10
+ Z> find @attr 1=1010 @attr 4=107 10
+ </screen>
+ </para>
+
+ <para>
+ In
+ the GILS schema (<literal>gils.abs</literal>), the
+ west-bounding-coordinate is indexed as type <literal>n</literal>,
+ and is therefore searched by specifying
+ <emphasis>structure</emphasis>=<emphasis>Numeric String</emphasis>.
+ To match all those records with west-bounding-coordinate greater
+ than -114 we use the following query:
+ <screen>
+ Z> find @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
+ </screen>
+ </para>
+ <note>
+ The exact mapping between PQF queries and Zebra internal indexes
+ and index types is explained in
+ <xref linkend="querymodel-pqf-apt-mapping"/>.
+ </note>
+
+ </sect3>
+
+ <sect3 id="querymodel-bib1-truncation">
+ <title>Truncation Attributes (type = 5)</title>
+
+ <para>
+ The truncation attribute specifies whether variations of one or
+ more characters are allowed between serch term and hit terms, or
+ not. Using non-default truncation attributes will broaden the
+ document hit set of a search query.
+ </para>
+
+ <table id="querymodel-bib1-truncation-table"
+ frame="all" rowsep="1" colsep="1" align="center">
+
+ <caption>Truncation Attributes (type 5)</caption>
+ <thead>
+ <tr>
+ <td>Truncation</td>
+ <td>Value</td>
+ <td>Notes</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Right truncation </td>
+ <td>1</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Left truncation</td>
+ <td>2</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Left and right truncation</td>
+ <td>3</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>Do not truncate</td>
+ <td>100</td>
+ <td>default</td>
+ </tr>
+ <tr>
+ <td>Process # in search term</td>
+ <td>101</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>RegExpr-1 </td>
+ <td>102</td>
+ <td>supported</td>
+ </tr>
+ <tr>
+ <td>RegExpr-2</td>
+ <td>103</td>
+ <td>supported</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <para>
+ The truncation attribute values 1-3 perform the obvious way:
+ <screen>
+ Z> scan @attr 1=Body-of-text schnittke
+ ...
+ * schnittke (81)
+ schnittkes (31)
+ schnittstelle (1)
+ ...
+ Z> find @attr 1=Body-of-text @attr 5=1 schnittke
+ ...
+ Number of hits: 95, setno 7
+ ...
+ Z> find @attr 1=Body-of-text @attr 5=2 schnittke
+ ...
+ Number of hits: 81, setno 6
+ ...
+ Z> find @attr 1=Body-of-text @attr 5=3 schnittke
+ ...
+ Number of hits: 95, setno 8
+ </screen>
+ </para>
+
+ <para>
+ The truncation attribute value
+ <literal>Process # in search term (101)</literal> is a
+ poor-man's regular expression search. It maps
+ each <literal>#</literal> to <literal>.*</literal>, and
+ performes then a <literal>Regexp-1 (102)</literal> regular
+ expression search. The following two queries are equivalent:
+ <screen>
+ Z> find @attr 1=Body-of-text @attr 5=101 schnit#ke
+ Z> find @attr 1=Body-of-text @attr 5=102 schnit.*ke
+ ...
+ Number of hits: 89, setno 10
+ </screen>
+ </para>
+
+ <para>
+ The truncation attribute value
+ <literal>Regexp-1 (102)</literal> is a normal regular search,
+ see <xref linkend="querymodel-regular"/> for details.
+ <screen>
+ Z> find @attr 1=Body-of-text @attr 5=102 schnit+ke
+ Z> find @attr 1=Body-of-text @attr 5=102 schni[a-t]+ke
+ </screen>
+ </para>
+
+ <para>
+ The truncation attribute value
+ <literal>Regexp-2 (103) </literal> is a Zebra specific extention
+ which allows <emphasis>fuzzy</emphasis> matches. One single
+ error in spelling of search terms is allowed, i.e., a document
+ is hit if it includes a term which can be mapped to the used
+ search term by one character substitution, addition, deletion or
+ change of posiiton.
+ <screen>
+ Z> find @attr 1=Body-of-text @attr 5=100 schnittke
+ ...
+ Number of hits: 81, setno 14
+ ...
+ Z> find @attr 1=Body-of-text @attr 5=103 schnittke
+ ...
+ Number of hits: 103, setno 15
+ ...
+ </screen>
+ </para>
+ </sect3>
+
+ <sect3 id="querymodel-bib1-completeness">
+ <title>Completeness Attributes (type = 6)</title>
+
+
+ <para>
+ The <literal>Completeness Attributes (type = 6)</literal>
+ is used to specify that a given search term or term list is either
+ part of the terms of a given index/field
+ (<literal>Incomplete subfield (1)</literal>), or is
+ what literally is found in the entire field's index
+ (<literal>Complete field (3)</literal>).
+ </para>
+
+ <table id="querymodel-bib1-completeness-table"
+ frame="all" rowsep="1" colsep="1" align="center">
+ <caption>Completeness Attributes (type = 6)</caption>
+ <thead>
+ <tr>
+ <td>Completeness</td>
+ <td>Value</td>
+ <td>Notes</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Incomplete subfield</td>
+ <td>1</td>
+ <td>default</td>
+ </tr>
+ <tr>
+ <td>Complete subfield</td>
+ <td>2</td>
+ <td>depreciated</td>
+ </tr>
+ <tr>
+ <td>Complete field</td>
+ <td>3</td>
+ <td>supported</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <para>
+ The <literal>Completeness Attributes (type = 6)</literal>
+ is only partially and conditionally
+ supported in the sense that it is ignored if the hit index is
+ not of structure <literal>type="w"</literal> or
+ <literal>type="p"</literal>.
+ </para>
+ <para>
+ <literal>Incomplete subfield (1)</literal> is the default, and
+ makes Zebra use
+ register <literal>type="w"</literal>, whereas
+ <literal>Complete field (3)</literal> triggers
+ search and scan in index <literal>type="p"</literal>.
+ </para>
+ <para>
+ The <literal>Complete subfield (2)</literal> is a reminiscens
+ from the happy <literal>MARC</literal>
+ binary format days. Zebra does not support it, but maps silently
+ to <literal>Complete field (3)</literal>.
+ </para>
+
+ <note>
+ The exact mapping between PQF queries and Zebra internal indexes
+ and index types is explained in
+ <xref linkend="querymodel-pqf-apt-mapping"/>.
+ </note>
+ </sect3>
+ </sect2>
+