docs/develop/Query-Processing-Modules.md

   1 # Writing custom query processing modules
   2
   3 Query processing allows to transform incoming queries before handing them
   4 to the search engine. Read more about them in the
   5 [Query Preprocessing](../customize/Query-Preprocessing.md) section.
   6
   7 ## Using custom preprocessing modules
   8
   9 To use a custom made preprocessing step, simply refer to the preprocessing module
  10 in the `step` property. There are two ways
  11 to include external modules: through a library or from the project directory.
  12
  13 To include a module from a library, use the absolute import path as name and
  14 make sure the library can be found in your PYTHONPATH.
  15
  16 !!! Example
  17     You have your preprocesser steps in a Python package my_modules and
  18     want to refer to the step implemented in module `delete_ip_addresses.py`.
  19
  20     ```
  21     - step: my_modules.delete_ip_addresses
  22       config: some other config info for the step
  23     ```
  24
  25 To use a custom module without creating a library, you can put the module
  26 somewhere in your project directory and then use the relative path to the
  27 file. Include the whole name of the file including the `.py` ending.
  28
  29 !!! Example
  30     You have put your module `delete_ip_addresses.py` directly into the project
  31     directory.
  32
  33     ```
  34     - step: delete_ip_addresses.py
  35       config: some other config info for the step
  36     ```
  37
  38 ## Basic sanitizer module setup
  39
  40 A query preprocessor must export a single factory function `create` with
  41 the following signature:
  42
  43 ``` python
  44 create(self, config: QueryConfig) -> Callable[[list[Phrase]], list[Phrase]]
  45 ```
  46
  47 The function receives the custom configuration for the preprocessor and
  48 returns a callable (function or class) with the actual preprocessing
  49 code. When a query comes in, then the callable gets a list of phrases
  50 and needs to return the transformed list of phrases. The list and phrases
  51 may be changed in place or a completely new list may be generated.
  52
  53 The `QueryConfig` is a simple dictionary which contains all configuration
  54 options given in the yaml configuration of the ICU tokenizer. It is up to
  55 the function to interpret the values.
  56
  57 A `nominatim_api.search.Phrase` describes a part of the query that contains one or more independent
  58 search terms. Breaking a query into phrases helps reducing the number of
  59 possible tokens Nominatim has to take into account. However a phrase break
  60 is definitive: a multi-term search word cannot go over a phrase break.
  61 A Phrase object has two fields:
  62
  63  * `ptype` further refines the type of phrase (see list below)
  64  * `text` contains the query text for the phrase
  65
  66 The order of phrases matters to Nominatim when doing further processing.
  67 Thus, while you may split or join phrases, you should not reorder them
  68 unless you really know what you are doing.
  69
  70 Phrase types can further help narrowing down how the tokens in the phrase
  71 are interpreted. The following phrase types are known:
  72
  73 | Name           | Description |
  74 |----------------|-------------|
  75 | PHRASE_ANY     | No specific designation (i.e. source is free-form query) |
  76 | PHRASE_AMENITY | Contains name or type of a POI |
  77 | PHRASE_STREET  | Contains a street name optionally with a housenumber |
  78 | PHRASE_CITY    | Contains the postal city |
  79 | PHRASE_COUNTY  | Contains the equivalent of a county |
  80 | PHRASE_STATE   | Contains a state or province |
  81 | PHRASE_POSTCODE| Contains a postal code |
  82 | PHRASE_COUNTRY | Contains the country name or code |
  83