docs/develop/Tokenizers.md

   1 # Tokenizers
   2
   3 The tokenizer is the component of Nominatim that is responsible for
   4 analysing names of OSM objects and queries. Nominatim provides different
   5 tokenizers that use different strategies for normalisation. This page describes
   6 how tokenizers are expected to work and the public API that needs to be
   7 implemented when creating a new tokenizer. For information on how to configure
   8 a specific tokenizer for a database see the
   9 [tokenizer chapter in the administration guide](../admin/Tokenizers.md).
  10
  11 ## Generic Architecture
  12
  13 ### About Search Tokens
  14
  15 Search in Nominatim is organised around search tokens. Such a token represents
  16 string that can be part of the search query. Tokens are used so that the search
  17 index does not need to be organised around strings. Instead the database saves
  18 for each place which tokens match this place's name, address, house number etc.
  19 To be able to distinguish between these different types of information stored
  20 with the place, a search token also always has a certain type: name, house number,
  21 postcode etc.
  22
  23 During search an incoming query is transformed into a ordered list of such
  24 search tokens (or rather many lists, see below) and this list is then converted
  25 into a database query to find the right place.
  26
  27 It is the core task of the tokenizer to create, manage and assign the search
  28 tokens. The tokenizer is involved in two distinct operations:
  29
  30 * __at import time__: scanning names of OSM objects, normalizing them and
  31   building up the list of search tokens.
  32 * __at query time__: scanning the query and returning the appropriate search
  33   tokens.
  34
  35
  36 ### Importing
  37
  38 The indexer is responsible to enrich an OSM object (or place) with all data
  39 required for geocoding. It is split into two parts: the controller collects
  40 the places that require updating, enriches the place information as required
  41 and hands the place to Postgresql. The collector is part of the Nominatim
  42 library written in Python. Within Postgresql, the `placex_update`
  43 trigger is responsible to fill out all secondary tables with extra geocoding
  44 information. This part is written in PL/pgSQL.
  45
  46 The tokenizer is involved in both parts. When the indexer prepares a place,
  47 it hands it over to the tokenizer to inspect the names and create all the
  48 search tokens applicable for the place. This usually involves updating the
  49 tokenizer's internal token lists and creating a list of all token IDs for
  50 the specific place. This list is later needed in the PL/pgSQL part where the
  51 indexer needs to add the token IDs to the appropriate search tables. To be
  52 able to communicate the list between the Python part and the pl/pgSQL trigger,
  53 the placex table contains a special JSONB column `token_info` which is there
  54 for the exclusive use of the tokenizer.
  55
  56 The Python part of the tokenizer returns a structured information about the
  57 tokens of a place to the indexer which converts it to JSON and inserts it into
  58 the `token_info` column. The content of the column is then handed to the PL/pqSQL
  59 callbacks of the tokenizer which extracts the required information. Usually
  60 the tokenizer then removes all information from the `token_info` structure,
  61 so that no information is ever persistently saved in the table. All information
  62 that went in should have been processed after all and put into secondary tables.
  63 This is however not a hard requirement. If the tokenizer needs to store
  64 additional information about a place permanently, it may do so in the
  65 `token_info` column. It just may never execute searches over it and
  66 consequently not create any special indexes on it.
  67
  68 ### Querying
  69
  70 The tokenizer is responsible for the initial parsing of the query. It needs
  71 to split the query into appropriate words and terms and match them against
  72 the saved tokens in the database. It then returns the list of possibly matching
  73 tokens and the list of possible splits to the query parser. The parser uses
  74 this information to compute all possible interpretations of the query and
  75 rank them accordingly.