]> git.openstreetmap.org Git - nominatim.git/blob - docs/develop/ICU-Tokenizer-Modules.md
63b1c3c1db5833f1f53225252f424d426e0941b8
[nominatim.git] / docs / develop / ICU-Tokenizer-Modules.md
1 # Writing custom sanitizer and token analysis modules for the ICU tokenizer
2
3 The [ICU tokenizer](../customize/Tokenizers.md#icu-tokenizer) provides a
4 highly customizable method to pre-process and normalize the name information
5 of the input data before it is added to the search index. It comes with a
6 selection of sanitizers and token analyzers which you can use to adapt your
7 installation to your needs. If the provided modules are not enough, you can
8 also provide your own implementations. This section describes the API
9 of sanitizers and token analysis.
10
11 !!! warning
12     This API is currently in early alpha status. While this API is meant to
13     be a public API on which other sanitizers and token analyzers may be
14     implemented, it is not guaranteed to be stable at the moment.
15
16
17 ## Using non-standard sanitizers and token analyzers
18
19 Sanitizer names (in the `step` property) and token analysis names (in the
20 `analyzer`) may refer to externally supplied modules. There are two ways
21 to include external modules: through a library or from the project directory.
22
23 To include a module from a library, use the absolute import path as name and
24 make sure the library can be found in your PYTHONPATH.
25
26 To use a custom module without creating a library, you can put the module
27 somewhere in your project directory and then use the relative path to the
28 file. Include the whole name of the file including the `.py` ending.
29
30 ## Custom sanitizer modules
31
32 A sanitizer module must export a single factory function `create` with the
33 following signature:
34
35 ``` python
36 def create(config: SanitizerConfig) -> Callable[[ProcessInfo], None]
37 ```
38
39 The function receives the custom configuration for the sanitizer and must
40 return a callable (function or class) that transforms the name and address
41 terms of a place. When a place is processed, then a `ProcessInfo` object
42 is created from the information that was queried from the database. This
43 object is sequentially handed to each configured sanitizer, so that each
44 sanitizer receives the result of processing from the previous sanitizer.
45 After the last sanitizer is finished, the resulting name and address lists
46 are forwarded to the token analysis module.
47
48 Sanitizer functions are instantiated once and then called for each place
49 that is imported or updated. They don't need to be thread-safe.
50 If multi-threading is used, each thread creates their own instance of
51 the function.
52
53 ### Sanitizer configuration
54
55 ::: nominatim.tokenizer.sanitizers.config.SanitizerConfig
56     options:
57         heading_level: 6
58
59 ### The main filter function of the sanitizer
60
61 The filter function receives a single object of type `ProcessInfo`
62 which has with three members:
63
64  * `place: PlaceInfo`: read-only information about the place being processed.
65    See PlaceInfo below.
66  * `names: List[PlaceName]`: The current list of names for the place.
67  * `address: List[PlaceName]`: The current list of address names for the place.
68
69 While the `place` member is provided for information only, the `names` and
70 `address` lists are meant to be manipulated by the sanitizer. It may add and
71 remove entries, change information within a single entry (for example by
72 adding extra attributes) or completely replace the list with a different one.
73
74 #### PlaceInfo - information about the place
75
76 ::: nominatim.data.place_info.PlaceInfo
77     options:
78         heading_level: 6
79
80
81 #### PlaceName - extended naming information
82
83 ::: nominatim.data.place_name.PlaceName
84     options:
85         heading_level: 6
86
87
88 ### Example: Filter for US street prefixes
89
90 The following sanitizer removes the directional prefixes from street names
91 in the US:
92
93 ``` python
94 import re
95
96 def _filter_function(obj):
97     if obj.place.country_code == 'us' \
98        and obj.place.rank_address >= 26 and obj.place.rank_address <= 27:
99         for name in obj.names:
100             name.name = re.sub(r'^(north|south|west|east) ',
101                                '',
102                                name.name,
103                                flags=re.IGNORECASE)
104
105 def create(config):
106     return _filter_function
107 ```
108
109 This is the most simple form of a sanitizer module. If defines a single
110 filter function and implements the required `create()` function by returning
111 the filter.
112
113 The filter function first checks if the object is interesting for the
114 sanitizer. Namely it checks if the place is in the US (through `country_code`)
115 and it the place is a street (a `rank_address` of 26 or 27). If the
116 conditions are met, then it goes through all available names and
117 removes any leading directional prefix using a simple regular expression.
118
119 Save the source code in a file in your project directory, for example as
120 `us_streets.py`. Then you can use the sanitizer in your `icu_tokenizer.yaml`:
121
122 ``` yaml
123 ...
124 sanitizers:
125     - step: us_streets.py
126 ...
127 ```
128
129 !!! warning
130     This example is just a simplified show case on how to create a sanitizer.
131     It is not really read for real-world use: while the sanitizer would
132     correcly transform `West 5th Street` into `5th Street`. it would also
133     shorten a simple `North Street` to `Street`.
134
135 For more sanitizer examples, have a look at the sanitizers provided by Nominatim.
136 They can be found in the directory
137 [`nominatim/tokenizer/sanitizers`](https://github.com/osm-search/Nominatim/tree/master/nominatim/tokenizer/sanitizers).
138
139
140 ## Custom token analysis module
141
142 ::: nominatim.tokenizer.token_analysis.base.AnalysisModule
143     options:
144         heading_level: 6
145
146
147 ::: nominatim.tokenizer.token_analysis.base.Analyzer
148     options:
149         heading_level: 6
150
151 ### Example: Creating acronym variants for long names
152
153 The following example of a token analysis module creates acronyms from
154 very long names and adds them as a variant:
155
156 ``` python
157 class AcronymMaker:
158     """ This class is the actual analyzer.
159     """
160     def __init__(self, norm, trans):
161         self.norm = norm
162         self.trans = trans
163
164
165     def get_canonical_id(self, name):
166         # In simple cases, the normalized name can be used as a canonical id.
167         return self.norm.transliterate(name.name).strip()
168
169
170     def compute_variants(self, name):
171         # The transliterated form of the name always makes up a variant.
172         variants = [self.trans.transliterate(name)]
173
174         # Only create acronyms from very long words.
175         if len(name) > 20:
176             # Take the first letter from each word to form the acronym.
177             acronym = ''.join(w[0] for w in name.split())
178             # If that leds to an acronym with at least three letters,
179             # add the resulting acronym as a variant.
180             if len(acronym) > 2:
181                 # Never forget to transliterate the variants before returning them.
182                 variants.append(self.trans.transliterate(acronym))
183
184         return variants
185
186 # The following two functions are the module interface.
187
188 def configure(rules, normalizer, transliterator):
189     # There is no configuration to parse and no data to set up.
190     # Just return an empty configuration.
191     return None
192
193
194 def create(normalizer, transliterator, config):
195     # Return a new instance of our token analysis class above.
196     return AcronymMaker(normalizer, transliterator)
197 ```
198
199 Given the name `Trans-Siberian Railway`, the code above would return the full
200 name `Trans-Siberian Railway` and the acronym `TSR` as variant, so that
201 searching would work for both.
202
203 ## Sanitizers vs. Token analysis - what to use for variants?
204
205 It is not always clear when to implement variations in the sanitizer and
206 when to write a token analysis module. Just take the acronym example
207 above: it would also have been possible to write a sanitizer which adds the
208 acronym as an additional name to the name list. The result would have been
209 similar. So which should be used when?
210
211 The most important thing to keep in mind is that variants created by the
212 token analysis are only saved in the word lookup table. They do not need
213 extra space in the search index. If there are many spelling variations, this
214 can mean quite a significant amount of space is saved.
215
216 When creating additional names with a sanitizer, these names are completely
217 independent. In particular, they can be fed into different token analysis
218 modules. This gives a much greater flexibility but at the price that the
219 additional names increase the size of the search index.
220