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