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