lib-sql/functions/ranking.sql

   1 -- SPDX-License-Identifier: GPL-2.0-only
   2 --
   3 -- This file is part of Nominatim. (https://nominatim.org)
   4 --
   5 -- Copyright (C) 2026 by the Nominatim developer community.
   6 -- For a full list of authors see the git log.
   7
   8 -- Functions related to search and address ranks
   9
  10 -- Function for removing the categories that shouldn't be taken into account while ranking.
  11 -- Categories outside the osm.* tree are always kept.
  12 CREATE OR REPLACE FUNCTION drop_unwanted_categories(categories ltree[], osm_type TEXT,
  13                                                     admin_level SMALLINT, name HSTORE,
  14                                                     extratags HSTORE, is_area BOOLEAN)
  15   RETURNS ltree[]
  16   AS $$
  17 DECLARE
  18   cat ltree;
  19   cat_class TEXT;
  20   result ltree[] := ARRAY[]::ltree[];
  21 BEGIN
  22   IF categories IS NULL THEN
  23     RETURN NULL;
  24   END IF;
  25
  26   FOREACH cat IN ARRAY categories LOOP
  27     IF cat::TEXT LIKE 'osm.%' THEN
  28       cat_class := subpath(cat, 1, 1)::TEXT;
  29
  30       -- Check unnamed highway area
  31       IF cat_class = 'highway'
  32         AND is_area AND name IS NULL
  33         AND extratags IS NOT NULL AND extratags ? 'area'
  34         AND extratags->'area' = 'yes'
  35       THEN
  36         CONTINUE;
  37       END IF;
  38
  39       -- Check non-area boundary
  40       IF cat_class = 'boundary' THEN
  41         IF NOT is_area OR (admin_level <= 4 AND osm_type = 'W')
  42         THEN
  43           CONTINUE;
  44         END IF;
  45       END IF;
  46     END IF;
  47
  48     result := array_append(result, cat);
  49   END LOOP;
  50
  51   RETURN result;
  52 END;
  53 $$
  54 LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
  55
  56 -- Check if a place is rankable at all.
  57 -- These really should be dropped at the lua level eventually.
  58 CREATE OR REPLACE FUNCTION is_rankable_place(osm_type TEXT, categories ltree[],
  59                                              admin_level SMALLINT, name HSTORE,
  60                                              extratags HSTORE, is_area BOOLEAN)
  61   RETURNS BOOLEAN
  62   AS $$
  63 BEGIN
  64   IF categories IS NULL THEN
  65     RETURN TRUE;
  66   END IF;
  67   RETURN array_length(drop_unwanted_categories(categories, osm_type, admin_level,
  68                       name, extratags, is_area), 1)
  69                       IS NOT NULL;
  70 END;
  71 $$
  72 LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
  73
  74
  75
  76 -- Return an approximate search radius according to the search rank.
  77 CREATE OR REPLACE FUNCTION reverse_place_diameter(rank_search SMALLINT)
  78   RETURNS FLOAT
  79   AS $$
  80 BEGIN
  81   IF rank_search <= 4 THEN
  82     RETURN 5.0;
  83   ELSIF rank_search <= 8 THEN
  84     RETURN 1.8;
  85   ELSIF rank_search <= 12 THEN
  86     RETURN 0.6;
  87   ELSIF rank_search <= 17 THEN
  88     RETURN 0.16;
  89   ELSIF rank_search <= 18 THEN
  90     RETURN 0.08;
  91   ELSIF rank_search <= 19 THEN
  92     RETURN 0.04;
  93   END IF;
  94
  95   RETURN 0.02;
  96 END;
  97 $$
  98 LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
  99
 100
 101 -- Return an approximate update radius according to the search rank.
 102 CREATE OR REPLACE FUNCTION update_place_diameter(rank_search SMALLINT)
 103   RETURNS FLOAT
 104   AS $$
 105 BEGIN
 106   -- postcodes
 107   IF rank_search = 11 or rank_search = 5 THEN
 108     RETURN 0.05;
 109   -- anything higher than city is effectively ignored (polygon required)
 110   ELSIF rank_search < 16 THEN
 111     RETURN 0;
 112   ELSIF rank_search < 18 THEN
 113     RETURN 0.1;
 114   ELSIF rank_search < 20 THEN
 115     RETURN 0.05;
 116   ELSIF rank_search = 21 THEN
 117     RETURN 0.001;
 118   ELSIF rank_search < 24 THEN
 119     RETURN 0.02;
 120   ELSIF rank_search < 26 THEN
 121     RETURN 0.005;
 122   ELSIF rank_search < 28 THEN
 123     RETURN 0.002;
 124   END IF;
 125
 126   RETURN 0;
 127 END;
 128 $$
 129 LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
 130
 131 -- Compute a base address rank from the extent of the given geometry.
 132 --
 133 -- This is all simple guess work. We don't need particularly good estimates
 134 -- here. This just avoids to have very high ranked address parts in features
 135 -- that span very large areas (or vice versa).
 136 CREATE OR REPLACE FUNCTION geometry_to_rank(search_rank SMALLINT, geometry GEOMETRY, country_code TEXT)
 137   RETURNS SMALLINT
 138   AS $$
 139 DECLARE
 140   area FLOAT;
 141 BEGIN
 142   IF ST_GeometryType(geometry) in ('ST_Polygon','ST_MultiPolygon') THEN
 143       area := ST_Area(geometry);
 144   ELSIF ST_GeometryType(geometry) in ('ST_LineString','ST_MultiLineString') THEN
 145       area := (ST_Length(geometry)^2) * 0.1;
 146   ELSE
 147     RETURN search_rank;
 148   END IF;
 149
 150   -- adjust for the fact that countries come in different sizes
 151   IF country_code IN ('ca', 'au', 'ru') THEN
 152     area := area / 5;
 153   ELSIF country_code IN ('br', 'kz', 'cn', 'us', 'ne', 'gb', 'za', 'sa', 'id', 'eh', 'ml', 'tm') THEN
 154     area := area / 3;
 155   ELSIF country_code IN ('bo', 'ar', 'sd', 'mn', 'in', 'et', 'cd', 'mz', 'ly', 'cl', 'zm') THEN
 156     area := area / 2;
 157   ELSIF country_code IN ('sg', 'ws', 'st', 'kn') THEN
 158     area := area * 5;
 159   ELSIF country_code IN ('dm', 'mt', 'lc', 'gg', 'sc', 'nr') THEN
 160     area := area * 20;
 161   END IF;
 162
 163   IF area > 1 THEN
 164     RETURN 7;
 165   ELSIF area > 0.1 THEN
 166     RETURN 9;
 167   ELSIF area > 0.01 THEN
 168     RETURN 13;
 169   ELSIF area > 0.001 THEN
 170     RETURN 17;
 171   ELSIF area > 0.0001 THEN
 172     RETURN 19;
 173   ELSIF area > 0.000005 THEN
 174     RETURN 21;
 175   END IF;
 176
 177    RETURN 23;
 178 END;
 179 $$
 180 LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
 181
 182
 183 -- Get standard search and address rank for an object.
 184 -- Iterates all osm.* categories and finds the one with the lowest positive
 185 -- address rank. Address rank of 0 has the lowest priority. Ties broken by
 186 -- lower search rank.
 187 --
 188 -- \param country        Two-letter country code where the object is in.
 189 -- \param extended_type  OSM type (N, W, R) or area type (A).
 190 -- \param categories     ltree[] of osm.<class>.<type> categories.
 191 -- \param admin_level    Value of admin_level tag.
 192 -- \param is_major       If true, boost search rank by one.
 193 -- \param postcode       Value of addr:postcode tag.
 194 -- \param[out] search_rank   Computed search rank.
 195 -- \param[out] address_rank  Computed address rank.
 196 --
 197 CREATE OR REPLACE FUNCTION compute_place_rank(country VARCHAR(2),
 198                                               extended_type VARCHAR(1),
 199                                               categories ltree[],
 200                                               admin_level SMALLINT,
 201                                               is_major BOOLEAN,
 202                                               postcode TEXT,
 203                                               OUT search_rank SMALLINT,
 204                                               OUT address_rank SMALLINT)
 205 AS $$
 206 DECLARE
 207   cat ltree;
 208   cat_class TEXT;
 209   cat_type TEXT;
 210   classtype TEXT;
 211   best_search SMALLINT := 99;
 212   best_address SMALLINT := 99;
 213   cand_search SMALLINT;
 214   cand_address SMALLINT;
 215   has_boundary_admin BOOLEAN;
 216 BEGIN
 217   IF categories IS NULL THEN
 218     search_rank := 30;
 219     address_rank := 30;
 220     RETURN;
 221   END IF;
 222
 223   -- Hoist: skip place categories when boundary/administrative is also present.
 224   has_boundary_admin := categories <@ 'osm.boundary.administrative';
 225
 226   FOREACH cat IN ARRAY categories LOOP
 227     -- Only consider osm.* categories
 228     IF NOT (cat ~ 'osm.*'::lquery) THEN
 229       CONTINUE;
 230     END IF;
 231
 232     -- Place ranks are handled by the post-hoc adjustment in placex_update.
 233     IF has_boundary_admin AND cat ~ 'osm.place.*'::lquery THEN
 234       CONTINUE;
 235     END IF;
 236
 237     cat_class := split_part(cat::text, '.', 2);
 238     cat_type := split_part(cat::text, '.', 3);
 239     -- Short-circuits for special cases
 240     IF extended_type = 'N' AND cat_class = 'highway' THEN
 241       cand_search := 30;
 242       cand_address := 30;
 243     ELSIF cat_class = 'landuse' AND extended_type != 'A' THEN
 244       cand_search := 30;
 245       cand_address := 30;
 246     ELSE
 247       -- Build classtype for boundary/administrative
 248       IF cat_class = 'boundary' AND cat_type = 'administrative' THEN
 249         classtype := cat_type || admin_level::TEXT;
 250       ELSE
 251         classtype := cat_type;
 252       END IF;
 253
 254       SELECT l.rank_search, l.rank_address INTO cand_search, cand_address
 255         FROM address_levels l
 256        WHERE (l.country_code = country OR l.country_code IS NULL)
 257              AND l.class = cat_class AND (l.type = classtype OR l.type IS NULL)
 258        ORDER BY l.country_code, l.class, l.type LIMIT 1;
 259
 260       IF cand_search IS NULL OR cand_address IS NULL THEN
 261         cand_search := 30;
 262         cand_address := 30;
 263       END IF;
 264
 265       -- Waterway relation boost
 266       IF cat_class = 'waterway' AND extended_type = 'R' THEN
 267         cand_search := cand_search - 1;
 268       END IF;
 269     END IF;
 270
 271     -- Selection: pick the candidate with lowest positive address rank.
 272     -- Address rank of 0 has lowest priority (fallback only). Tiebreak: lower search rank.
 273     -- A positive address rank always overrides a zero-address fallback (best_address = 0).
 274     IF cand_address > 0 AND (best_address = 0 OR cand_address < best_address) THEN
 275       best_search := cand_search;
 276       best_address := cand_address;
 277     ELSIF cand_address > 0 AND cand_address = best_address
 278           AND cand_search < best_search THEN
 279       best_search := cand_search;
 280       best_address := cand_address;
 281     ELSIF cand_address = 0 AND (best_address = 99 OR best_address = 0)
 282           AND cand_search < best_search THEN
 283       -- Fallback: when no addressable category found, pick best search rank
 284       best_search := cand_search;
 285       best_address := cand_address;
 286     END IF;
 287   END LOOP;
 288
 289   -- Apply is_major boost to the winner
 290   IF is_major THEN
 291     best_search := best_search - 1;
 292   END IF;
 293
 294   search_rank := best_search;
 295   address_rank := best_address;
 296 END;
 297 $$
 298 LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
 299
 300 CREATE OR REPLACE FUNCTION get_addr_tag_rank(key TEXT, country TEXT,
 301                                              OUT from_rank SMALLINT,
 302                                              OUT to_rank SMALLINT,
 303                                              OUT extent FLOAT)
 304   AS $$
 305 DECLARE
 306   ranks RECORD;
 307 BEGIN
 308   from_rank := null;
 309
 310   FOR ranks IN
 311     SELECT * FROM
 312       (SELECT l.rank_search, l.rank_address FROM address_levels l
 313         WHERE (l.country_code = country or l.country_code is NULL)
 314                AND l.class = 'place' AND l.type = key
 315         ORDER BY l.country_code LIMIT 1) r
 316       WHERE rank_address > 0
 317   LOOP
 318     extent := reverse_place_diameter(ranks.rank_search);
 319
 320     IF ranks.rank_address <= 4 THEN
 321         from_rank := 4;
 322         to_rank := 4;
 323     ELSEIF ranks.rank_address <= 9 THEN
 324         from_rank := 5;
 325         to_rank := 9;
 326     ELSEIF ranks.rank_address <= 12 THEN
 327         from_rank := 10;
 328         to_rank := 12;
 329     ELSEIF ranks.rank_address <= 16 THEN
 330         from_rank := 13;
 331         to_rank := 16;
 332     ELSEIF ranks.rank_address <= 21 THEN
 333         from_rank := 17;
 334         to_rank := 21;
 335     ELSEIF ranks.rank_address <= 24 THEN
 336         from_rank := 22;
 337         to_rank := 24;
 338     ELSE
 339         from_rank := 25;
 340         to_rank := 25;
 341     END IF;
 342   END LOOP;
 343 END;
 344 $$
 345 LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
 346
 347
 348 CREATE OR REPLACE FUNCTION weigh_search(search_vector INT[],
 349                                         rankings TEXT,
 350                                         def_weight FLOAT)
 351   RETURNS FLOAT
 352   AS $$
 353 DECLARE
 354   rank JSON;
 355 BEGIN
 356   FOR rank IN
 357     SELECT * FROM json_array_elements(rankings::JSON)
 358   LOOP
 359     IF true = ALL(SELECT x::int = ANY(search_vector) FROM json_array_elements_text(rank->1) as x) THEN
 360       RETURN (rank->>0)::float;
 361     END IF;
 362   END LOOP;
 363   RETURN def_weight;
 364 END;
 365 $$
 366 LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;