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. There is a more complete explanation of what prefixes are in used by a standard recoll installation. In a nutshell: extension prefixes should be all caps, begin with XY, and short. E.g. XYMFLD.
- [values]
Fields listed in this section will be stored as Xapian
valuesinside the index. This makes them available for range queries, allowing to filter results according to the field value. This feature currently supports string and integer data. See the comments in the file for more detail- [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
