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 automatically installed and used when upgrading an older
  23 database. It should not be used for new installations anymore.
  24
  25 ### Compiling the PostgreSQL module
  26
  27 The tokeinzer needs a special C module for PostgreSQL which is not compiled
  28 by default. If you need the legacy tokenizer, compile Nominatim as follows:
  29
  30 ```
  31 mkdir build
  32 cd build
  33 cmake -DBUILD_MODULE=on
  34 make
  35 ```
  36
  37 ### Enabling the tokenizer
  38
  39 To enable the tokenizer add the following line to your project configuration:
  40
  41 ```
  42 NOMINATIM_TOKENIZER=legacy
  43 ```
  44
  45 The Postgresql module for the tokenizer is available in the `module` directory
  46 and also installed with the remainder of the software under
  47 `lib/nominatim/module/nominatim.so`. You can specify a custom location for
  48 the module with
  49
  50 ```
  51 NOMINATIM_DATABASE_MODULE_PATH=<path to directory where nominatim.so resides>
  52 ```
  53
  54 This is in particular useful when the database runs on a different server.
  55 See [Advanced installations](../admin/Advanced-Installations.md#importing-nominatim-to-an-external-postgresql-database) for details.
  56
  57 There are no other configuration options for the legacy tokenizer. All
  58 normalization functions are hard-coded.
  59
  60 ## ICU tokenizer
  61
  62 The ICU tokenizer uses the [ICU library](http://site.icu-project.org/) to
  63 normalize names and queries. It also offers configurable decomposition and
  64 abbreviation handling.
  65 This tokenizer is currently the default.
  66
  67 To enable the tokenizer add the following line to your project configuration:
  68
  69 ```
  70 NOMINATIM_TOKENIZER=icu
  71 ```
  72
  73 ### How it works
  74
  75 On import the tokenizer processes names in the following three stages:
  76
  77 1. During the **Sanitizer step** incoming names are cleaned up and converted to
  78    **full names**. This step can be used to regularize spelling, split multi-name
  79    tags into their parts and tag names with additional attributes. See the
  80    [Sanitizers section](#sanitizers) below for available cleaning routines.
  81 2. The **Normalization** part removes all information from the full names
  82    that are not relevant for search.
  83 3. The **Token analysis** step takes the normalized full names and creates
  84    all transliterated variants under which the name should be searchable.
  85    See the [Token analysis](#token-analysis) section below for more
  86    information.
  87
  88 During query time, only normalization and transliteration are relevant.
  89 An incoming query is first split into name chunks (this usually means splitting
  90 the string at the commas) and the each part is normalised and transliterated.
  91 The result is used to look up places in the search index.
  92
  93 ### Configuration
  94
  95 The ICU tokenizer is configured using a YAML file which can be configured using
  96 `NOMINATIM_TOKENIZER_CONFIG`. The configuration is read on import and then
  97 saved as part of the internal database status. Later changes to the variable
  98 have no effect.
  99
 100 Here is an example configuration file:
 101
 102 ``` yaml
 103 normalization:
 104     - ":: lower ()"
 105     - "ß > 'ss'" # German szet is unambiguously equal to double ss
 106 transliteration:
 107     - !include /etc/nominatim/icu-rules/extended-unicode-to-asccii.yaml
 108     - ":: Ascii ()"
 109 sanitizers:
 110     - step: split-name-list
 111 token-analysis:
 112     - analyzer: generic
 113       variants:
 114           - !include icu-rules/variants-ca.yaml
 115           - words:
 116               - road -> rd
 117               - bridge -> bdge,br,brdg,bri,brg
 118       mutations:
 119           - pattern: 'ä'
 120             replacements: ['ä', 'ae']
 121 ```
 122
 123 The configuration file contains four sections:
 124 `normalization`, `transliteration`, `sanitizers` and `token-analysis`.
 125
 126 #### Normalization and Transliteration
 127
 128 The normalization and transliteration sections each define a set of
 129 ICU rules that are applied to the names.
 130
 131 The **normalization** rules are applied after sanitation. They should remove
 132 any information that is not relevant for search at all. Usual rules to be
 133 applied here are: lower-casing, removing of special characters, cleanup of
 134 spaces.
 135
 136 The **transliteration** rules are applied at the end of the tokenization
 137 process to transfer the name into an ASCII representation. Transliteration can
 138 be useful to allow for further fuzzy matching, especially between different
 139 scripts.
 140
 141 Each section must contain a list of
 142 [ICU transformation rules](https://unicode-org.github.io/icu/userguide/transforms/general/rules.html).
 143 The rules are applied in the order in which they appear in the file.
 144 You can also include additional rules from external yaml file using the
 145 `!include` tag. The included file must contain a valid YAML list of ICU rules
 146 and may again include other files.
 147
 148 !!! warning
 149     The ICU rule syntax contains special characters that conflict with the
 150     YAML syntax. You should therefore always enclose the ICU rules in
 151     double-quotes.
 152
 153 #### Sanitizers
 154
 155 The sanitizers section defines an ordered list of functions that are applied
 156 to the name and address tags before they are further processed by the tokenizer.
 157 They allows to clean up the tagging and bring it to a standardized form more
 158 suitable for building the search index.
 159
 160 !!! hint
 161     Sanitizers only have an effect on how the search index is built. They
 162     do not change the information about each place that is saved in the
 163     database. In particular, they have no influence on how the results are
 164     displayed. The returned results always show the original information as
 165     stored in the OpenStreetMap database.
 166
 167 Each entry contains information of a sanitizer to be applied. It has a
 168 mandatory parameter `step` which gives the name of the sanitizer. Depending
 169 on the type, it may have additional parameters to configure its operation.
 170
 171 The order of the list matters. The sanitizers are applied exactly in the order
 172 that is configured. Each sanitizer works on the results of the previous one.
 173
 174 The following is a list of sanitizers that are shipped with Nominatim.
 175
 176 ##### split-name-list
 177
 178 ::: nominatim_db.tokenizer.sanitizers.split_name_list
 179     options:
 180         members: False
 181         heading_level: 6
 182         docstring_section_style: spacy
 183
 184 ##### strip-brace-terms
 185
 186 ::: nominatim_db.tokenizer.sanitizers.strip_brace_terms
 187     options:
 188         members: False
 189         heading_level: 6
 190         docstring_section_style: spacy
 191
 192 ##### tag-analyzer-by-language
 193
 194 ::: nominatim_db.tokenizer.sanitizers.tag_analyzer_by_language
 195     options:
 196         members: False
 197         heading_level: 6
 198         docstring_section_style: spacy
 199
 200 ##### clean-housenumbers
 201
 202 ::: nominatim_db.tokenizer.sanitizers.clean_housenumbers
 203     options:
 204         members: False
 205         heading_level: 6
 206         docstring_section_style: spacy
 207
 208 ##### clean-postcodes
 209
 210 ::: nominatim_db.tokenizer.sanitizers.clean_postcodes
 211     options:
 212         members: False
 213         heading_level: 6
 214         docstring_section_style: spacy
 215
 216 ##### clean-tiger-tags
 217
 218 ::: nominatim_db.tokenizer.sanitizers.clean_tiger_tags
 219     options:
 220         members: False
 221         heading_level: 6
 222         docstring_section_style: spacy
 223
 224 #### delete-tags
 225
 226 ::: nominatim_db.tokenizer.sanitizers.delete_tags
 227     options:
 228         members: False
 229         heading_level: 6
 230         docstring_section_style: spacy
 231
 232 #### tag-japanese
 233
 234 ::: nominatim_db.tokenizer.sanitizers.tag_japanese
 235     options:
 236         members: False
 237         heading_level: 6
 238         docstring_section_style: spacy
 239
 240 #### Token Analysis
 241
 242 Token analyzers take a full name and transform it into one or more normalized
 243 form that are then saved in the search index. In its simplest form, the
 244 analyzer only applies the transliteration rules. More complex analyzers
 245 create additional spelling variants of a name. This is useful to handle
 246 decomposition and abbreviation.
 247
 248 The ICU tokenizer may use different analyzers for different names. To select
 249 the analyzer to be used, the name must be tagged with the `analyzer` attribute
 250 by a sanitizer (see for example the
 251 [tag-analyzer-by-language sanitizer](#tag-analyzer-by-language)).
 252
 253 The token-analysis section contains the list of configured analyzers. Each
 254 analyzer must have an `id` parameter that uniquely identifies the analyzer.
 255 The only exception is the default analyzer that is used when no special
 256 analyzer was selected. There are analysers with special ids:
 257
 258  * '@housenumber'. If an analyzer with that name is present, it is used
 259    for normalization of house numbers.
 260  * '@potcode'. If an analyzer with that name is present, it is used
 261    for normalization of postcodes.
 262
 263 Different analyzer implementations may exist. To select the implementation,
 264 the `analyzer` parameter must be set. The different implementations are
 265 described in the following.
 266
 267 ##### Generic token analyzer
 268
 269 The generic analyzer `generic` is able to create variants from a list of given
 270 abbreviation and decomposition replacements and introduce spelling variations.
 271
 272 ###### Variants
 273
 274 The optional 'variants' section defines lists of replacements which create alternative
 275 spellings of a name. To create the variants, a name is scanned from left to
 276 right and the longest matching replacement is applied until the end of the
 277 string is reached.
 278
 279 The variants section must contain a list of replacement groups. Each group
 280 defines a set of properties that describes where the replacements are
 281 applicable. In addition, the word section defines the list of replacements
 282 to be made. The basic replacement description is of the form:
 283
 284 ```
 285 <source>[,<source>[...]] => <target>[,<target>[...]]
 286 ```
 287
 288 The left side contains one or more `source` terms to be replaced. The right side
 289 lists one or more replacements. Each source is replaced with each replacement
 290 term.
 291
 292 !!! tip
 293     The source and target terms are internally normalized using the
 294     normalization rules given in the configuration. This ensures that the
 295     strings match as expected. In fact, it is better to use unnormalized
 296     words in the configuration because then it is possible to change the
 297     rules for normalization later without having to adapt the variant rules.
 298
 299 ###### Decomposition
 300
 301 In its standard form, only full words match against the source. There
 302 is a special notation to match the prefix and suffix of a word:
 303
 304 ``` yaml
 305 - ~strasse => str  # matches "strasse" as full word and in suffix position
 306 - hinter~ => hntr  # matches "hinter" as full word and in prefix position
 307 ```
 308
 309 There is no facility to match a string in the middle of the word. The suffix
 310 and prefix notation automatically trigger the decomposition mode: two variants
 311 are created for each replacement, one with the replacement attached to the word
 312 and one separate. So in above example, the tokenization of "hauptstrasse" will
 313 create the variants "hauptstr" and "haupt str". Similarly, the name "rote strasse"
 314 triggers the variants "rote str" and "rotestr". By having decomposition work
 315 both ways, it is sufficient to create the variants at index time. The variant
 316 rules are not applied at query time.
 317
 318 To avoid automatic decomposition, use the '|' notation:
 319
 320 ``` yaml
 321 - ~strasse |=> str
 322 ```
 323
 324 simply changes "hauptstrasse" to "hauptstr" and "rote strasse" to "rote str".
 325
 326 ###### Initial and final terms
 327
 328 It is also possible to restrict replacements to the beginning and end of a
 329 name:
 330
 331 ``` yaml
 332 - ^south => s  # matches only at the beginning of the name
 333 - road$ => rd  # matches only at the end of the name
 334 ```
 335
 336 So the first example would trigger a replacement for "south 45th street" but
 337 not for "the south beach restaurant".
 338
 339 ###### Replacements vs. variants
 340
 341 The replacement syntax `source => target` works as a pure replacement. It changes
 342 the name instead of creating a variant. To create an additional version, you'd
 343 have to write `source => source,target`. As this is a frequent case, there is
 344 a shortcut notation for it:
 345
 346 ```
 347 <source>[,<source>[...]] -> <target>[,<target>[...]]
 348 ```
 349
 350 The simple arrow causes an additional variant to be added. Note that
 351 decomposition has an effect here on the source as well. So a rule
 352
 353 ``` yaml
 354 - "~strasse -> str"
 355 ```
 356
 357 means that for a word like `hauptstrasse` four variants are created:
 358 `hauptstrasse`, `haupt strasse`, `hauptstr` and `haupt str`.
 359
 360 ###### Mutations
 361
 362 The 'mutation' section in the configuration describes an additional set of
 363 replacements to be applied after the variants have been computed.
 364
 365 Each mutation is described by two parameters: `pattern` and `replacements`.
 366 The pattern must contain a single regular expression to search for in the
 367 variant name. The regular expressions need to follow the syntax for
 368 [Python regular expressions](file:///usr/share/doc/python3-doc/html/library/re.html#regular-expression-syntax).
 369 Capturing groups are not permitted.
 370 `replacements` must contain a list of strings that the pattern
 371 should be replaced with. Each occurrence of the pattern is replaced with
 372 all given replacements. Be mindful of combinatorial explosion of variants.
 373
 374 ###### Modes
 375
 376 The generic analyser supports a special mode `variant-only`. When configured
 377 then it consumes the input token and emits only variants (if any exist). Enable
 378 the mode by adding:
 379
 380 ```
 381   mode: variant-only
 382 ```
 383
 384 to the analyser configuration.
 385
 386 ##### Housenumber token analyzer
 387
 388 The analyzer `housenumbers` is purpose-made to analyze house numbers. It
 389 creates variants with optional spaces between numbers and letters. Thus,
 390 house numbers of the form '3 a', '3A', '3-A' etc. are all considered equivalent.
 391
 392 The analyzer cannot be customized.
 393
 394 ##### Postcode token analyzer
 395
 396 The analyzer `postcodes` is pupose-made to analyze postcodes. It supports
 397 a 'lookup' variant of the token, which produces variants with optional
 398 spaces. Use together with the clean-postcodes sanitizer.
 399
 400 The analyzer cannot be customized.
 401
 402 ### Reconfiguration
 403
 404 Changing the configuration after the import is currently not possible, although
 405 this feature may be added at a later time.