# Recoll user manual
Configuration overview

Sidebar | Prev | Up | Next

### The fields file

This file contains information about dynamic fields handling in Recoll. Some very basic fields have hard-wired behaviour, and, mostly, you should not change the original data inside the `fields` file. But you can create custom fields fitting your data and handle them just like they were native ones.

The `fields` file has several sections, which each define an aspect of fields processing. Quite often, you'll have to modify several sections to obtain the desired behaviour.

We will only give a short description here, you should refer to the comments inside the default file for more detailed information.

Field names should be lowercase alphabetic ASCII.

[prefixes]

  A field becomes indexed (searchable) by having a prefix defined in this section.

[stored]

  A field becomes stored (displayable inside results) by having its name listed in this section (typically with an empty value).

[aliases]

  This section defines lists of synonyms for the canonical names used inside the `[prefixes]` and `[stored]` sections

[queryaliases]

  This section also defines aliases for the canonic field names, with the difference that the substitution will only be used at query time, avoiding any possibility that the value would pick-up random metadata from documents.

handler-specific sections

  Some input handlers may need specific configuration for handling fields. Only the email message handler currently has such a section (named `[mail]`). It allows indexing arbitrary email headers in addition to the ones indexed by default. Other such sections may appear in the future.

Here follows a small example of a personal `fields` file. This would extract a specific email header and use it as a searchable field, with data displayable inside result lists. (Side note: as the email handler does no decoding on the values, only plain ascii headers can be indexed, and only the first occurrence will be used for headers that occur several times).

    [prefixes]
    # Index mailmytag contents (with the given prefix)
    mailmytag = XMTAG

    [stored]
    # Store mailmytag inside the document data record (so that it can be
    # displayed - as %(mailmytag) - in result lists).
    mailmytag =

    [queryaliases]
    filename = fn
    containerfilename = cfn

    [mail]
    # Extract the X-My-Tag mail header, and use it internally with the
    # mailmytag field name
    x-my-tag = mailmytag

Prev | Up | Next
| Home |