Next: Right truncation, Previous: Indexing, Up: Tutorial

### 1.3 Searching

Here is a simple searching command:

         $ af -s -d mydb -Q 'cat & (dog | mouse)'

The `-s` option tells `af` that this is a search operation. The `-q` option specifies a Boolean search query, which represents what you are searching for. The entire query is enclosed between two apostrophes so that the UNIX shell will not modify its contents. The special characters, ‘`&`’ and ‘`|`’, are Boolean operators meaning `and' and `or' respectively. In other words, the above query means, “Find all documents that contain the word, ‘`cat`’, and that also contain either ‘`dog`’ or ‘`mouse`’.” Note that these words are `case-insensitive', meaning that ‘`cat`’, ‘`CAT`’, and ‘`caT`’ are interchangeable.

The command returns a list of matching document references, each one taking the form:

         + score dbname docid parent filename begin end

where ‘`score`’ is a relevance score, ‘`dbname`’ is the database name, ‘`docid`’ is an unique number identifying the document within the database, ‘`parent`’ is the docid of the document that “contains” this document (or 0 if no such relationship exists), ‘`filename`’ is the name of the file containing the document, and ‘`begin`’ and ‘`end`’ are byte offsets indicating the beginning and ending of the document within the file. Often there is a one-to-one correspondence between files and documents, in which case the ‘`begin`’ and ‘`end`’ values may be ignored. The ‘`dbname`’ value is only useful if one is searching multiple databases at once (for example, see Multiple databases).

In the above example the words, ‘`cat`’, ‘`dog`’, and ‘`mouse`’, are each an individual query term. When the `-Q` option is used, Amberfish searches for each query term separately and then combines the results according to the Boolean operators. Amberfish also supports a non-Boolean free-text query type, which is invoked by using `-q` instead of `-Q`. It consists of a list of terms separated by spaces and no Boolean operators, for example:

         $ af -s -d mydb -q 'cat dog mouse'

This is roughly similar to a Boolean query with all the terms joined by ‘`or`’, such as:

         $ af -s -d mydb -Q 'cat | dog | mouse'

Note: The free-text search option (`-q`) is not yet fully implemented but is planned for an upcoming release. For now please use `-Q` when trying the examples in this tutorial.

In the next several examples we concentrate on the structure of a single query term, with the understanding that terms can be combined arbitrarily into Boolean expressions or free-text queries.