nominatim/tokenizer/legacy_icu_tokenizer.py

   1 """
   2 Tokenizer implementing normalisation as used before Nominatim 4 but using
   3 libICU instead of the PostgreSQL module.
   4 """
   5 from collections import Counter
   6 import itertools
   7 import logging
   8 import re
   9 from textwrap import dedent
  10 from pathlib import Path
  11
  12 from nominatim.db.connection import connect
  13 from nominatim.db.properties import set_property, get_property
  14 from nominatim.db.utils import CopyBuffer
  15 from nominatim.db.sql_preprocessor import SQLPreprocessor
  16 from nominatim.tokenizer.icu_rule_loader import ICURuleLoader
  17 from nominatim.tokenizer.icu_name_processor import ICUNameProcessor, ICUNameProcessorRules
  18
  19 DBCFG_MAXWORDFREQ = "tokenizer_maxwordfreq"
  20 DBCFG_TERM_NORMALIZATION = "tokenizer_term_normalization"
  21
  22 LOG = logging.getLogger()
  23
  24 def create(dsn, data_dir):
  25     """ Create a new instance of the tokenizer provided by this module.
  26     """
  27     return LegacyICUTokenizer(dsn, data_dir)
  28
  29
  30 class LegacyICUTokenizer:
  31     """ This tokenizer uses libICU to covert names and queries to ASCII.
  32         Otherwise it uses the same algorithms and data structures as the
  33         normalization routines in Nominatim 3.
  34     """
  35
  36     def __init__(self, dsn, data_dir):
  37         self.dsn = dsn
  38         self.data_dir = data_dir
  39         self.naming_rules = None
  40         self.term_normalization = None
  41         self.max_word_frequency = None
  42
  43
  44     def init_new_db(self, config, init_db=True):
  45         """ Set up a new tokenizer for the database.
  46
  47             This copies all necessary data in the project directory to make
  48             sure the tokenizer remains stable even over updates.
  49         """
  50         if config.TOKENIZER_CONFIG:
  51             cfgfile = Path(config.TOKENIZER_CONFIG)
  52         else:
  53             cfgfile = config.config_dir / 'legacy_icu_tokenizer.yaml'
  54
  55         loader = ICURuleLoader(cfgfile)
  56         self.naming_rules = ICUNameProcessorRules(loader=loader)
  57         self.term_normalization = config.TERM_NORMALIZATION
  58         self.max_word_frequency = config.MAX_WORD_FREQUENCY
  59
  60         self._install_php(config.lib_dir.php)
  61         self._save_config(config)
  62
  63         if init_db:
  64             self.update_sql_functions(config)
  65             self._init_db_tables(config)
  66
  67
  68     def init_from_project(self):
  69         """ Initialise the tokenizer from the project directory.
  70         """
  71         with connect(self.dsn) as conn:
  72             self.naming_rules = ICUNameProcessorRules(conn=conn)
  73             self.term_normalization = get_property(conn, DBCFG_TERM_NORMALIZATION)
  74             self.max_word_frequency = get_property(conn, DBCFG_MAXWORDFREQ)
  75
  76
  77     def finalize_import(self, config):
  78         """ Do any required postprocessing to make the tokenizer data ready
  79             for use.
  80         """
  81         with connect(self.dsn) as conn:
  82             sqlp = SQLPreprocessor(conn, config)
  83             sqlp.run_sql_file(conn, 'tokenizer/legacy_tokenizer_indices.sql')
  84
  85
  86     def update_sql_functions(self, config):
  87         """ Reimport the SQL functions for this tokenizer.
  88         """
  89         with connect(self.dsn) as conn:
  90             max_word_freq = get_property(conn, DBCFG_MAXWORDFREQ)
  91             sqlp = SQLPreprocessor(conn, config)
  92             sqlp.run_sql_file(conn, 'tokenizer/legacy_icu_tokenizer.sql',
  93                               max_word_freq=max_word_freq)
  94
  95
  96     def check_database(self):
  97         """ Check that the tokenizer is set up correctly.
  98         """
  99         self.init_from_project()
 100
 101         if self.naming_rules is None:
 102             return "Configuration for tokenizer 'legacy_icu' are missing."
 103
 104         return None
 105
 106
 107     def name_analyzer(self):
 108         """ Create a new analyzer for tokenizing names and queries
 109             using this tokinzer. Analyzers are context managers and should
 110             be used accordingly:
 111
 112             ```
 113             with tokenizer.name_analyzer() as analyzer:
 114                 analyser.tokenize()
 115             ```
 116
 117             When used outside the with construct, the caller must ensure to
 118             call the close() function before destructing the analyzer.
 119
 120             Analyzers are not thread-safe. You need to instantiate one per thread.
 121         """
 122         return LegacyICUNameAnalyzer(self.dsn, ICUNameProcessor(self.naming_rules))
 123
 124     # pylint: disable=missing-format-attribute
 125     def _install_php(self, phpdir):
 126         """ Install the php script for the tokenizer.
 127         """
 128         php_file = self.data_dir / "tokenizer.php"
 129         php_file.write_text(dedent("""\
 130             <?php
 131             @define('CONST_Max_Word_Frequency', {0.max_word_frequency});
 132             @define('CONST_Term_Normalization_Rules', "{0.term_normalization}");
 133             @define('CONST_Transliteration', "{0.naming_rules.search_rules}");
 134             require_once('{1}/tokenizer/legacy_icu_tokenizer.php');
 135             """.format(self, phpdir)))
 136
 137
 138     def _save_config(self, config):
 139         """ Save the configuration that needs to remain stable for the given
 140             database as database properties.
 141         """
 142         with connect(self.dsn) as conn:
 143             self.naming_rules.save_rules(conn)
 144
 145             set_property(conn, DBCFG_MAXWORDFREQ, config.MAX_WORD_FREQUENCY)
 146             set_property(conn, DBCFG_TERM_NORMALIZATION, self.term_normalization)
 147
 148
 149     def _init_db_tables(self, config):
 150         """ Set up the word table and fill it with pre-computed word
 151             frequencies.
 152         """
 153         with connect(self.dsn) as conn:
 154             sqlp = SQLPreprocessor(conn, config)
 155             sqlp.run_sql_file(conn, 'tokenizer/icu_tokenizer_tables.sql')
 156             conn.commit()
 157
 158             LOG.warning("Precomputing word tokens")
 159
 160             # get partial words and their frequencies
 161             words = Counter()
 162             name_proc = ICUNameProcessor(self.naming_rules)
 163             with conn.cursor(name="words") as cur:
 164                 cur.execute(""" SELECT v, count(*) FROM
 165                                   (SELECT svals(name) as v FROM place)x
 166                                 WHERE length(v) < 75 GROUP BY v""")
 167
 168                 for name, cnt in cur:
 169                     terms = set()
 170                     for word in name_proc.get_variants_ascii(name_proc.get_normalized(name)):
 171                         if ' ' in word:
 172                             terms.update(word.split())
 173                     for term in terms:
 174                         words[term] += cnt
 175
 176             # copy them back into the word table
 177             with CopyBuffer() as copystr:
 178                 for args in words.items():
 179                     copystr.add(*args)
 180
 181                 with conn.cursor() as cur:
 182                     copystr.copy_out(cur, 'word',
 183                                      columns=['word_token', 'search_name_count'])
 184                     cur.execute("""UPDATE word SET word_id = nextval('seq_word')
 185                                    WHERE word_id is null""")
 186
 187             conn.commit()
 188
 189
 190 class LegacyICUNameAnalyzer:
 191     """ The legacy analyzer uses the ICU library for splitting names.
 192
 193         Each instance opens a connection to the database to request the
 194         normalization.
 195     """
 196
 197     def __init__(self, dsn, name_proc):
 198         self.conn = connect(dsn).connection
 199         self.conn.autocommit = True
 200         self.name_processor = name_proc
 201
 202         self._cache = _TokenCache()
 203
 204
 205     def __enter__(self):
 206         return self
 207
 208
 209     def __exit__(self, exc_type, exc_value, traceback):
 210         self.close()
 211
 212
 213     def close(self):
 214         """ Free all resources used by the analyzer.
 215         """
 216         if self.conn:
 217             self.conn.close()
 218             self.conn = None
 219
 220
 221     def get_word_token_info(self, words):
 222         """ Return token information for the given list of words.
 223             If a word starts with # it is assumed to be a full name
 224             otherwise is a partial name.
 225
 226             The function returns a list of tuples with
 227             (original word, word token, word id).
 228
 229             The function is used for testing and debugging only
 230             and not necessarily efficient.
 231         """
 232         tokens = {}
 233         for word in words:
 234             if word.startswith('#'):
 235                 tokens[word] = ' ' + self.name_processor.get_search_normalized(word[1:])
 236             else:
 237                 tokens[word] = self.name_processor.get_search_normalized(word)
 238
 239         with self.conn.cursor() as cur:
 240             cur.execute("""SELECT word_token, word_id
 241                            FROM word, (SELECT unnest(%s::TEXT[]) as term) t
 242                            WHERE word_token = t.term
 243                                  and class is null and country_code is null""",
 244                         (list(tokens.values()), ))
 245             ids = {r[0]: r[1] for r in cur}
 246
 247         return [(k, v, ids.get(v, None)) for k, v in tokens.items()]
 248
 249
 250     @staticmethod
 251     def normalize_postcode(postcode):
 252         """ Convert the postcode to a standardized form.
 253
 254             This function must yield exactly the same result as the SQL function
 255             'token_normalized_postcode()'.
 256         """
 257         return postcode.strip().upper()
 258
 259
 260     def _make_standard_hnr(self, hnr):
 261         """ Create a normalised version of a housenumber.
 262
 263             This function takes minor shortcuts on transliteration.
 264         """
 265         return self.name_processor.get_search_normalized(hnr)
 266
 267     def update_postcodes_from_db(self):
 268         """ Update postcode tokens in the word table from the location_postcode
 269             table.
 270         """
 271         to_delete = []
 272         with self.conn.cursor() as cur:
 273             # This finds us the rows in location_postcode and word that are
 274             # missing in the other table.
 275             cur.execute("""SELECT * FROM
 276                             (SELECT pc, word FROM
 277                               (SELECT distinct(postcode) as pc FROM location_postcode) p
 278                               FULL JOIN
 279                               (SELECT info->>'postcode' as word FROM word WHERE type = 'P') w
 280                               ON pc = word) x
 281                            WHERE pc is null or word is null""")
 282
 283             with CopyBuffer() as copystr:
 284                 for postcode, word in cur:
 285                     if postcode is None:
 286                         to_delete.append(word)
 287                     else:
 288                         copystr.add(self.name_processor.get_search_normalized(postcode),
 289                                     'P', {'postcode': postcode})
 290
 291                 if to_delete:
 292                     cur.execute("""DELETE FROM WORD
 293                                    WHERE class ='P' and info->>'postcode' = any(%s)
 294                                 """, (to_delete, ))
 295
 296                 copystr.copy_out(cur, 'word',
 297                                  columns=['word_token', 'type', 'info'])
 298
 299
 300     def update_special_phrases(self, phrases, should_replace):
 301         """ Replace the search index for special phrases with the new phrases.
 302         """
 303         norm_phrases = set(((self.name_processor.get_normalized(p[0]), p[1], p[2], p[3])
 304                             for p in phrases))
 305
 306         with self.conn.cursor() as cur:
 307             # Get the old phrases.
 308             existing_phrases = set()
 309             cur.execute("""SELECT word, class, type, operator FROM word
 310                            WHERE class != 'place'
 311                                  OR (type != 'house' AND type != 'postcode')""")
 312             for label, cls, typ, oper in cur:
 313                 existing_phrases.add((label, cls, typ, oper or '-'))
 314
 315             added = self._add_special_phrases(cur, norm_phrases, existing_phrases)
 316             if should_replace:
 317                 deleted = self._remove_special_phrases(cur, norm_phrases,
 318                                                        existing_phrases)
 319             else:
 320                 deleted = 0
 321
 322         LOG.info("Total phrases: %s. Added: %s. Deleted: %s",
 323                  len(norm_phrases), added, deleted)
 324
 325
 326     def _add_special_phrases(self, cursor, new_phrases, existing_phrases):
 327         """ Add all phrases to the database that are not yet there.
 328         """
 329         to_add = new_phrases - existing_phrases
 330
 331         added = 0
 332         with CopyBuffer() as copystr:
 333             for word, cls, typ, oper in to_add:
 334                 term = self.name_processor.get_search_normalized(word)
 335                 if term:
 336                     copystr.add(word, ' ' + term, cls, typ,
 337                                 oper if oper in ('in', 'near') else None, 0)
 338                     added += 1
 339
 340             copystr.copy_out(cursor, 'word',
 341                              columns=['word', 'word_token', 'class', 'type',
 342                                       'operator', 'search_name_count'])
 343
 344         return added
 345
 346
 347     @staticmethod
 348     def _remove_special_phrases(cursor, new_phrases, existing_phrases):
 349         """ Remove all phrases from the databse that are no longer in the
 350             new phrase list.
 351         """
 352         to_delete = existing_phrases - new_phrases
 353
 354         if to_delete:
 355             cursor.execute_values(
 356                 """ DELETE FROM word USING (VALUES %s) as v(name, in_class, in_type, op)
 357                     WHERE word = name and class = in_class and type = in_type
 358                           and ((op = '-' and operator is null) or op = operator)""",
 359                 to_delete)
 360
 361         return len(to_delete)
 362
 363
 364     def add_country_names(self, country_code, names):
 365         """ Add names for the given country to the search index.
 366         """
 367         word_tokens = set()
 368         for name in self._compute_full_names(names):
 369             norm_name = self.name_processor.get_search_normalized(name)
 370             if norm_name:
 371                 word_tokens.add(norm_name)
 372
 373         with self.conn.cursor() as cur:
 374             # Get existing names
 375             cur.execute("""SELECT word_token FROM word
 376                             WHERE type = 'C' and info->>'cc'= %s""",
 377                         (country_code, ))
 378             word_tokens.difference_update((t[0] for t in cur))
 379
 380             # Only add those names that are not yet in the list.
 381             if word_tokens:
 382                 cur.execute("""INSERT INTO word (word_token, type, info)
 383                                (SELECT token, 'C', json_build_object('cc', %s)
 384                                 FROM unnest(%s) as token)
 385                             """, (country_code, list(word_tokens)))
 386
 387             # No names are deleted at the moment.
 388             # If deletion is made possible, then the static names from the
 389             # initial 'country_name' table should be kept.
 390
 391
 392     def process_place(self, place):
 393         """ Determine tokenizer information about the given place.
 394
 395             Returns a JSON-serialisable structure that will be handed into
 396             the database via the token_info field.
 397         """
 398         token_info = _TokenInfo(self._cache)
 399
 400         names = place.get('name')
 401
 402         if names:
 403             fulls, partials = self._compute_name_tokens(names)
 404
 405             token_info.add_names(fulls, partials)
 406
 407             country_feature = place.get('country_feature')
 408             if country_feature and re.fullmatch(r'[A-Za-z][A-Za-z]', country_feature):
 409                 self.add_country_names(country_feature.lower(), names)
 410
 411         address = place.get('address')
 412         if address:
 413             self._process_place_address(token_info, address)
 414
 415         return token_info.data
 416
 417
 418     def _process_place_address(self, token_info, address):
 419         hnrs = []
 420         addr_terms = []
 421         for key, value in address.items():
 422             if key == 'postcode':
 423                 self._add_postcode(value)
 424             elif key in ('housenumber', 'streetnumber', 'conscriptionnumber'):
 425                 hnrs.append(value)
 426             elif key == 'street':
 427                 token_info.add_street(*self._compute_name_tokens({'name': value}))
 428             elif key == 'place':
 429                 token_info.add_place(*self._compute_name_tokens({'name': value}))
 430             elif not key.startswith('_') and \
 431                  key not in ('country', 'full'):
 432                 addr_terms.append((key, *self._compute_name_tokens({'name': value})))
 433
 434         if hnrs:
 435             hnrs = self._split_housenumbers(hnrs)
 436             token_info.add_housenumbers(self.conn, [self._make_standard_hnr(n) for n in hnrs])
 437
 438         if addr_terms:
 439             token_info.add_address_terms(addr_terms)
 440
 441
 442     def _compute_name_tokens(self, names):
 443         """ Computes the full name and partial name tokens for the given
 444             dictionary of names.
 445         """
 446         full_names = self._compute_full_names(names)
 447         full_tokens = set()
 448         partial_tokens = set()
 449
 450         for name in full_names:
 451             norm_name = self.name_processor.get_normalized(name)
 452             full, part = self._cache.names.get(norm_name, (None, None))
 453             if full is None:
 454                 variants = self.name_processor.get_variants_ascii(norm_name)
 455                 if not variants:
 456                     continue
 457
 458                 with self.conn.cursor() as cur:
 459                     cur.execute("SELECT (getorcreate_full_word(%s, %s)).*",
 460                                 (norm_name, variants))
 461                     full, part = cur.fetchone()
 462
 463                 self._cache.names[norm_name] = (full, part)
 464
 465             full_tokens.add(full)
 466             partial_tokens.update(part)
 467
 468         return full_tokens, partial_tokens
 469
 470
 471     @staticmethod
 472     def _compute_full_names(names):
 473         """ Return the set of all full name word ids to be used with the
 474             given dictionary of names.
 475         """
 476         full_names = set()
 477         for name in (n.strip() for ns in names.values() for n in re.split('[;,]', ns)):
 478             if name:
 479                 full_names.add(name)
 480
 481                 brace_idx = name.find('(')
 482                 if brace_idx >= 0:
 483                     full_names.add(name[:brace_idx].strip())
 484
 485         return full_names
 486
 487
 488     def _add_postcode(self, postcode):
 489         """ Make sure the normalized postcode is present in the word table.
 490         """
 491         if re.search(r'[:,;]', postcode) is None:
 492             postcode = self.normalize_postcode(postcode)
 493
 494             if postcode not in self._cache.postcodes:
 495                 term = self.name_processor.get_search_normalized(postcode)
 496                 if not term:
 497                     return
 498
 499                 with self.conn.cursor() as cur:
 500                     # no word_id needed for postcodes
 501                     cur.execute("""INSERT INTO word (word_token, type, info)
 502                                    (SELECT %s, 'P', json_build_object('postcode', pc)
 503                                     FROM (VALUES (%s)) as v(pc)
 504                                     WHERE NOT EXISTS
 505                                      (SELECT * FROM word
 506                                       WHERE type = 'P' and info->>postcode = pc))
 507                                 """, (term, postcode))
 508                 self._cache.postcodes.add(postcode)
 509
 510
 511     @staticmethod
 512     def _split_housenumbers(hnrs):
 513         if len(hnrs) > 1 or ',' in hnrs[0] or ';' in hnrs[0]:
 514             # split numbers if necessary
 515             simple_list = []
 516             for hnr in hnrs:
 517                 simple_list.extend((x.strip() for x in re.split(r'[;,]', hnr)))
 518
 519             if len(simple_list) > 1:
 520                 hnrs = list(set(simple_list))
 521             else:
 522                 hnrs = simple_list
 523
 524         return hnrs
 525
 526
 527
 528
 529 class _TokenInfo:
 530     """ Collect token information to be sent back to the database.
 531     """
 532     def __init__(self, cache):
 533         self._cache = cache
 534         self.data = {}
 535
 536     @staticmethod
 537     def _mk_array(tokens):
 538         return '{%s}' % ','.join((str(s) for s in tokens))
 539
 540
 541     def add_names(self, fulls, partials):
 542         """ Adds token information for the normalised names.
 543         """
 544         self.data['names'] = self._mk_array(itertools.chain(fulls, partials))
 545
 546
 547     def add_housenumbers(self, conn, hnrs):
 548         """ Extract housenumber information from a list of normalised
 549             housenumbers.
 550         """
 551         self.data['hnr_tokens'] = self._mk_array(self._cache.get_hnr_tokens(conn, hnrs))
 552         self.data['hnr'] = ';'.join(hnrs)
 553
 554
 555     def add_street(self, fulls, _):
 556         """ Add addr:street match terms.
 557         """
 558         if fulls:
 559             self.data['street'] = self._mk_array(fulls)
 560
 561
 562     def add_place(self, fulls, partials):
 563         """ Add addr:place search and match terms.
 564         """
 565         if fulls:
 566             self.data['place_search'] = self._mk_array(itertools.chain(fulls, partials))
 567             self.data['place_match'] = self._mk_array(fulls)
 568
 569
 570     def add_address_terms(self, terms):
 571         """ Add additional address terms.
 572         """
 573         tokens = {}
 574
 575         for key, fulls, partials in terms:
 576             if fulls:
 577                 tokens[key] = [self._mk_array(itertools.chain(fulls, partials)),
 578                                self._mk_array(fulls)]
 579
 580         if tokens:
 581             self.data['addr'] = tokens
 582
 583
 584 class _TokenCache:
 585     """ Cache for token information to avoid repeated database queries.
 586
 587         This cache is not thread-safe and needs to be instantiated per
 588         analyzer.
 589     """
 590     def __init__(self):
 591         self.names = {}
 592         self.postcodes = set()
 593         self.housenumbers = {}
 594
 595
 596     def get_hnr_tokens(self, conn, terms):
 597         """ Get token ids for a list of housenumbers, looking them up in the
 598             database if necessary. `terms` is an iterable of normalized
 599             housenumbers.
 600         """
 601         tokens = []
 602         askdb = []
 603
 604         for term in terms:
 605             token = self.housenumbers.get(term)
 606             if token is None:
 607                 askdb.append(term)
 608             else:
 609                 tokens.append(token)
 610
 611         if askdb:
 612             with conn.cursor() as cur:
 613                 cur.execute("SELECT nr, getorcreate_hnr_id(nr) FROM unnest(%s) as nr",
 614                             (askdb, ))
 615                 for term, tid in cur:
 616                     self.housenumbers[term] = tid
 617                     tokens.append(tid)
 618
 619         return tokens