docs/customize/Tokenizers.md

   1 # Tokenizers
   2
   3 The tokenizer module in Nominatim is responsible for analysing the names given
   4 to OSM objects and the terms of an incoming query in order to make sure, they
   5 can be matched appropriately.
   6
   7 Nominatim offers different tokenizer modules, which behave differently and have
   8 different configuration options. This sections describes the tokenizers and how
   9 they can be configured.
  10
  11 !!! important
  12     The use of a tokenizer is tied to a database installation. You need to choose
  13     and configure the tokenizer before starting the initial import. Once the import
  14     is done, you cannot switch to another tokenizer anymore. Reconfiguring the
  15     chosen tokenizer is very limited as well. See the comments in each tokenizer
  16     section.
  17
  18 ## Legacy tokenizer
  19
  20 The legacy tokenizer implements the analysis algorithms of older Nominatim
  21 versions. It uses a special Postgresql module to normalize names and queries.
  22 This tokenizer is currently the default.
  23
  24 To enable the tokenizer add the following line to your project configuration:
  25
  26 ```
  27 NOMINATIM_TOKENIZER=legacy
  28 ```
  29
  30 The Postgresql module for the tokenizer is available in the `module` directory
  31 and also installed with the remainder of the software under
  32 `lib/nominatim/module/nominatim.so`. You can specify a custom location for
  33 the module with
  34
  35 ```
  36 NOMINATIM_DATABASE_MODULE_PATH=<path to directory where nominatim.so resides>
  37 ```
  38
  39 This is in particular useful when the database runs on a different server.
  40 See [Advanced installations](Advanced-Installations.md#importing-nominatim-to-an-external-postgresql-database) for details.
  41
  42 There are no other configuration options for the legacy tokenizer. All
  43 normalization functions are hard-coded.
  44
  45 ## ICU tokenizer
  46
  47 The ICU tokenizer uses the [ICU library](http://site.icu-project.org/) to
  48 normalize names and queries. It also offers configurable decomposition and
  49 abbreviation handling.
  50
  51 To enable the tokenizer add the following line to your project configuration:
  52
  53 ```
  54 NOMINATIM_TOKENIZER=icu
  55 ```
  56
  57 ### How it works
  58
  59 On import the tokenizer processes names in the following three stages:
  60
  61 1. During the **Sanitizer step** incoming names are cleaned up and converted to
  62    **full names**. This step can be used to regularize spelling, split multi-name
  63    tags into their parts and tag names with additional attributes. See the
  64    [Sanitizers section](#sanitizers) below for available cleaning routines.
  65 2. The **Normalization** part removes all information from the full names
  66    that are not relevant for search.
  67 3. The **Token analysis** step takes the normalized full names and creates
  68    all transliterated variants under which the name should be searchable.
  69    See the [Token analysis](#token-analysis) section below for more
  70    information.
  71
  72 During query time, only normalization and transliteration are relevant.
  73 An incoming query is first split into name chunks (this usually means splitting
  74 the string at the commas) and the each part is normalised and transliterated.
  75 The result is used to look up places in the search index.
  76
  77 ### Configuration
  78
  79 The ICU tokenizer is configured using a YAML file which can be configured using
  80 `NOMINATIM_TOKENIZER_CONFIG`. The configuration is read on import and then
  81 saved as part of the internal database status. Later changes to the variable
  82 have no effect.
  83
  84 Here is an example configuration file:
  85
  86 ``` yaml
  87 normalization:
  88     - ":: lower ()"
  89     - "ß > 'ss'" # German szet is unimbigiously equal to double ss
  90 transliteration:
  91     - !include /etc/nominatim/icu-rules/extended-unicode-to-asccii.yaml
  92     - ":: Ascii ()"
  93 sanitizers:
  94     - step: split-name-list
  95 token-analysis:
  96     - analyzer: generic
  97       variants:
  98           - !include icu-rules/variants-ca.yaml
  99           - words:
 100               - road -> rd
 101               - bridge -> bdge,br,brdg,bri,brg
 102 ```
 103
 104 The configuration file contains four sections:
 105 `normalization`, `transliteration`, `sanitizers` and `token-analysis`.
 106
 107 #### Normalization and Transliteration
 108
 109 The normalization and transliteration sections each define a set of
 110 ICU rules that are applied to the names.
 111
 112 The **normalisation** rules are applied after sanitation. They should remove
 113 any information that is not relevant for search at all. Usual rules to be
 114 applied here are: lower-casing, removing of special characters, cleanup of
 115 spaces.
 116
 117 The **transliteration** rules are applied at the end of the tokenization
 118 process to transfer the name into an ASCII representation. Transliteration can
 119 be useful to allow for further fuzzy matching, especially between different
 120 scripts.
 121
 122 Each section must contain a list of
 123 [ICU transformation rules](https://unicode-org.github.io/icu/userguide/transforms/general/rules.html).
 124 The rules are applied in the order in which they appear in the file.
 125 You can also include additional rules from external yaml file using the
 126 `!include` tag. The included file must contain a valid YAML list of ICU rules
 127 and may again include other files.
 128
 129 !!! warning
 130     The ICU rule syntax contains special characters that conflict with the
 131     YAML syntax. You should therefore always enclose the ICU rules in
 132     double-quotes.
 133
 134 #### Sanitizers
 135
 136 The sanitizers section defines an ordered list of functions that are applied
 137 to the name and address tags before they are further processed by the tokenizer.
 138 They allows to clean up the tagging and bring it to a standardized form more
 139 suitable for building the search index.
 140
 141 !!! hint
 142     Sanitizers only have an effect on how the search index is built. They
 143     do not change the information about each place that is saved in the
 144     database. In particular, they have no influence on how the results are
 145     displayed. The returned results always show the original information as
 146     stored in the OpenStreetMap database.
 147
 148 Each entry contains information of a sanitizer to be applied. It has a
 149 mandatory parameter `step` which gives the name of the sanitizer. Depending
 150 on the type, it may have additional parameters to configure its operation.
 151
 152 The order of the list matters. The sanitizers are applied exactly in the order
 153 that is configured. Each sanitizer works on the results of the previous one.
 154
 155 The following is a list of sanitizers that are shipped with Nominatim.
 156
 157 ##### split-name-list
 158
 159 ::: nominatim.tokenizer.sanitizers.split_name_list
 160     selection:
 161         members: False
 162     rendering:
 163         heading_level: 6
 164
 165 ##### strip-brace-terms
 166
 167 ::: nominatim.tokenizer.sanitizers.strip_brace_terms
 168     selection:
 169         members: False
 170     rendering:
 171         heading_level: 6
 172
 173 ##### tag-analyzer-by-language
 174
 175 ::: nominatim.tokenizer.sanitizers.tag_analyzer_by_language
 176     selection:
 177         members: False
 178     rendering:
 179         heading_level: 6
 180
 181
 182
 183 #### Token Analysis
 184
 185 Token analyzers take a full name and transform it into one or more normalized
 186 form that are then saved in the search index. In its simplest form, the
 187 analyzer only applies the transliteration rules. More complex analyzers
 188 create additional spelling variants of a name. This is useful to handle
 189 decomposition and abbreviation.
 190
 191 The ICU tokenizer may use different analyzers for different names. To select
 192 the analyzer to be used, the name must be tagged with the `analyzer` attribute
 193 by a sanitizer (see for example the
 194 [tag-analyzer-by-language sanitizer](#tag-analyzer-by-language)).
 195
 196 The token-analysis section contains the list of configured analyzers. Each
 197 analyzer must have an `id` parameter that uniquely identifies the analyzer.
 198 The only exception is the default analyzer that is used when no special
 199 analyzer was selected.
 200
 201 Different analyzer implementations may exist. To select the implementation,
 202 the `analyzer` parameter must be set. Currently there is only one implementation
 203 `generic` which is described in the following.
 204
 205 ##### Generic token analyzer
 206
 207 The generic analyzer is able to create variants from a list of given
 208 abbreviation and decomposition replacements. It takes one optional parameter
 209 `variants` which lists the replacements to apply. If the section is
 210 omitted, then the generic analyzer becomes a simple analyzer that only
 211 applies the transliteration.
 212
 213 The variants section defines lists of replacements which create alternative
 214 spellings of a name. To create the variants, a name is scanned from left to
 215 right and the longest matching replacement is applied until the end of the
 216 string is reached.
 217
 218 The variants section must contain a list of replacement groups. Each group
 219 defines a set of properties that describes where the replacements are
 220 applicable. In addition, the word section defines the list of replacements
 221 to be made. The basic replacement description is of the form:
 222
 223 ```
 224 <source>[,<source>[...]] => <target>[,<target>[...]]
 225 ```
 226
 227 The left side contains one or more `source` terms to be replaced. The right side
 228 lists one or more replacements. Each source is replaced with each replacement
 229 term.
 230
 231 !!! tip
 232     The source and target terms are internally normalized using the
 233     normalization rules given in the configuration. This ensures that the
 234     strings match as expected. In fact, it is better to use unnormalized
 235     words in the configuration because then it is possible to change the
 236     rules for normalization later without having to adapt the variant rules.
 237
 238 ###### Decomposition
 239
 240 In its standard form, only full words match against the source. There
 241 is a special notation to match the prefix and suffix of a word:
 242
 243 ``` yaml
 244 - ~strasse => str  # matches "strasse" as full word and in suffix position
 245 - hinter~ => hntr  # matches "hinter" as full word and in prefix position
 246 ```
 247
 248 There is no facility to match a string in the middle of the word. The suffix
 249 and prefix notation automatically trigger the decomposition mode: two variants
 250 are created for each replacement, one with the replacement attached to the word
 251 and one separate. So in above example, the tokenization of "hauptstrasse" will
 252 create the variants "hauptstr" and "haupt str". Similarly, the name "rote strasse"
 253 triggers the variants "rote str" and "rotestr". By having decomposition work
 254 both ways, it is sufficient to create the variants at index time. The variant
 255 rules are not applied at query time.
 256
 257 To avoid automatic decomposition, use the '|' notation:
 258
 259 ``` yaml
 260 - ~strasse |=> str
 261 ```
 262
 263 simply changes "hauptstrasse" to "hauptstr" and "rote strasse" to "rote str".
 264
 265 ###### Initial and final terms
 266
 267 It is also possible to restrict replacements to the beginning and end of a
 268 name:
 269
 270 ``` yaml
 271 - ^south => s  # matches only at the beginning of the name
 272 - road$ => rd  # matches only at the end of the name
 273 ```
 274
 275 So the first example would trigger a replacement for "south 45th street" but
 276 not for "the south beach restaurant".
 277
 278 ###### Replacements vs. variants
 279
 280 The replacement syntax `source => target` works as a pure replacement. It changes
 281 the name instead of creating a variant. To create an additional version, you'd
 282 have to write `source => source,target`. As this is a frequent case, there is
 283 a shortcut notation for it:
 284
 285 ```
 286 <source>[,<source>[...]] -> <target>[,<target>[...]]
 287 ```
 288
 289 The simple arrow causes an additional variant to be added. Note that
 290 decomposition has an effect here on the source as well. So a rule
 291
 292 ``` yaml
 293 - "~strasse -> str"
 294 ```
 295
 296 means that for a word like `hauptstrasse` four variants are created:
 297 `hauptstrasse`, `haupt strasse`, `hauptstr` and `haupt str`.
 298
 299 ### Reconfiguration
 300
 301 Changing the configuration after the import is currently not possible, although
 302 this feature may be added at a later time.