From: Sarah Hoffmann Date: Mon, 9 Oct 2017 22:15:56 +0000 (+0200) Subject: documentation for SearchContext and SearchDescription X-Git-Tag: v3.1.0~47^2 X-Git-Url: https://git.openstreetmap.org/nominatim.git/commitdiff_plain/c8780da19c32c2ce5f6ea02d86a9db2d96e27195 documentation for SearchContext and SearchDescription --- diff --git a/lib/SearchContext.php b/lib/SearchContext.php index 9bab8658..134b138f 100644 --- a/lib/SearchContext.php +++ b/lib/SearchContext.php @@ -34,27 +34,67 @@ class SearchContext private $sqlExcludeList = ''; + /** + * Check if a reference point is defined. + * + * @return bool True if a reference point is defined. + */ public function hasNearPoint() { return $this->fNearRadius !== false; } + /** + * Get radius around reference point. + * + * @return float Search radius around refernce point. + */ public function nearRadius() { return $this->fNearRadius; } + /** + * Set search reference point in WGS84. + * + * If set, then only places around this point will be taken into account. + * + * @param float $fLat Latitude of point. + * @param float $fLon Longitude of point. + * @param float $fRadius Search radius around point. + * + * @return void + */ public function setNearPoint($fLat, $fLon, $fRadius = 0.1) { $this->fNearRadius = $fRadius; $this->sqlNear = 'ST_SetSRID(ST_Point('.$fLon.','.$fLat.'),4326)'; } + /** + * Check if the search is geographically restricted. + * + * Searches are restricted if a reference point is given or if + * a bounded viewbox is set. + * + * @return bool True, if the search is geographically bounded. + */ public function isBoundedSearch() { return $this->hasNearPoint() || ($this->sqlViewboxSmall && $this->bViewboxBounded); } + /** + * Set rectangular viewbox. + * + * The viewbox may be bounded which means that no search results + * must be outside the viewbox. + * + * @param float[4] $aViewBox Coordinates of the viewbox. + * @param bool $bBounded True if the viewbox is bounded. + * + * @return void + */ public function setViewboxFromBox(&$aViewBox, $bBounded) { $this->bViewboxBounded = $bBounded; @@ -80,6 +120,19 @@ class SearchContext ); } + /** + * Set viewbox along a route. + * + * The viewbox may be bounded which means that no search results + * must be outside the viewbox. + * + * @param object $oDB DB connection to use for computing the box. + * @param string[] $aRoutePoints List of x,y coordinates along a route. + * @param float $fRouteWidth Buffer around the route to use. + * @param bool $bBounded True if the viewbox bounded. + * + * @return void + */ public function setViewboxFromRoute(&$oDB, $aRoutePoints, $fRouteWidth, $bBounded) { $this->bViewboxBounded = $bBounded; @@ -101,22 +154,36 @@ class SearchContext $this->sqlViewboxLarge = "'".$sGeom."'::geometry"; } + /** + * Set list of excluded place IDs. + * + * @param integer[] $aExcluded List of IDs. + * + * @return void + */ public function setExcludeList($aExcluded) { $this->sqlExcludeList = ' not in ('.join(',', $aExcluded).')'; } + /** + * Set list of countries to restrict search to. + * + * @param string[] $aCountries List of two-letter lower-case country codes. + * + * @return void + */ public function setCountryList($aCountries) { $this->sqlCountryList = '('.join(',', array_map('addQuotes', $aCountries)).')'; } /** - * Extract a coordinate point from a query string. + * Extract a reference point from a query string. * * @param string $sQuery Query to scan. * - * @return The remaining query string. + * @return string The remaining query string. */ public function setNearPointFromQuery($sQuery) { @@ -135,16 +202,41 @@ class SearchContext return $sQuery; } + /** + * Get an SQL snipped for computing the distance from the reference point. + * + * @param string $sObj SQL variable name to compute the distance from. + * + * @return string An SQL string. + */ public function distanceSQL($sObj) { return 'ST_Distance('.$this->sqlNear.", $sObj)"; } + /** + * Get an SQL snipped for checking if something is within range of the + * reference point. + * + * @param string $sObj SQL variable name to compute if it is within range. + * + * @return string An SQL string. + */ public function withinSQL($sObj) { return sprintf('ST_DWithin(%s, %s, %F)', $sObj, $this->sqlNear, $this->fNearRadius); } + /** + * Get an SQL snipped of the importance factor of the viewbox. + * + * The importance factor is computed by checking if an object is within + * the viewbox and/or the extended version of the viewbox. + * + * @param string $sObj SQL variable name of object to weight the importance + * + * @return string SQL snipped of the factor with a leading multiply sign. + */ public function viewboxImportanceSQL($sObj) { $sSQL = ''; @@ -159,6 +251,14 @@ class SearchContext return $sSQL; } + /** + * SQL snipped checking if a place ID should be excluded. + * + * @param string $sVariable SQL variable name of place ID to check, + * potentially prefixed with more SQL. + * + * @return string SQL snippet. + */ public function excludeSQL($sVariable) { if ($this->sqlExcludeList) { diff --git a/lib/SearchDescription.php b/lib/SearchDescription.php index c287c898..1f3765ab 100644 --- a/lib/SearchDescription.php +++ b/lib/SearchDescription.php @@ -43,22 +43,55 @@ class SearchDescription private $iNamePhrase = -1; + /** + * Create an empty search description. + * + * @param object $oContext Global context to use. Will be inherited by + * all derived search objects. + */ public function __construct($oContext) { $this->oContext = $oContext; } + /** + * Get current search rank. + * + * The higher the search rank the lower the likelyhood that the + * search is a correct interpretation of the search query. + * + * @return integer Search rank. + */ public function getRank() { return $this->iSearchRank; } + /** + * Increase the search rank. + * + * @param integer $iAddRank Number of ranks to increase. + * + * @return void + */ public function addToRank($iAddRank) { $this->iSearchRank += $iAddRank; return $this->iSearchRank; } + /** + * Make this search a POI search. + * + * In a POI search, objects are not (only) searched by their name + * but also by the primary OSM key/value pair (class and type in Nominatim). + * + * @param integer $iOperator Type of POI search + * @param string $sClass Class (or OSM tag key) of POI. + * @param string $sType Type (or OSM tag value) of POI. + * + * @return void + */ public function setPoiSearch($iOperator, $sClass, $sType) { $this->iOperator = $iOperator; @@ -66,6 +99,11 @@ class SearchDescription $this->sType = $sType; } + /** + * Check if this might be a full address search. + * + * @return bool True if the search contains name, address and housenumber. + */ public function looksLikeFullAddress() { return sizeof($this->aName) @@ -73,11 +111,27 @@ class SearchDescription && preg_match('/[0-9]+/', $this->sHouseNumber); } + /** + * Check if any operator is set. + * + * @return bool True, if this is a special search operation. + */ public function hasOperator() { return $this->iOperator != Operator::NONE; } + /** + * Extract key/value pairs from a query. + * + * Key/value pairs are recognised if they are of the form [=]. + * If multiple terms of this kind are found then all terms are removed + * but only the first is used for search. + * + * @param string $sQuery Original query string. + * + * @return string The query string with the special search patterns removed. + */ public function extractKeyValuePairs($sQuery) { // Search for terms of kind [=]. @@ -98,6 +152,13 @@ class SearchDescription return $sQuery; } + /** + * Check if the combination of parameters is sensible. + * + * @param string[] $aCountryCodes List of country codes. + * + * @return bool True, if the search looks valid. + */ public function isValidSearch(&$aCountryCodes) { if (!sizeof($this->aName)) { @@ -118,6 +179,25 @@ class SearchDescription /////////// Search building functions + /** + * Derive new searches by adding a full term to the existing search. + * + * @param mixed[] $aSearchTerm Description of the token. + * @param bool $bWordInQuery True, if the normalised version of the word + * is contained in the query. + * @param bool $bHasPartial True if there are also tokens of partial terms + * with the same name. + * @param string $sPhraseType Type of phrase the token is contained in. + * @param bool $bFirstToken True if the token is at the beginning of the + * query. + * @param bool $bFirstPhrase True if the token is in the first phrase of + * the query. + * @param bool $bLastToken True if the token is at the end of the query. + * @param integer $iGlobalRank Changable ranking of all searches in the + * batch. + * + * @return SearchDescription[] List of derived search descriptions. + */ public function extendWithFullTerm($aSearchTerm, $bWordInQuery, $bHasPartial, $sPhraseType, $bFirstToken, $bFirstPhrase, $bLastToken, &$iGlobalRank) { $aNewSearches = array(); @@ -247,6 +327,19 @@ class SearchDescription return $aNewSearches; } + /** + * Derive new searches by adding a partial term to the existing search. + * + * @param mixed[] $aSearchTerm Description of the token. + * @param bool $bStructuredPhrases True if the search is structured. + * @param integer $iPhrase Number of the phrase the token is in. + * @param mixed[] $aWordFrequencyScores Number of times tokens appears + * overall in a planet database. + * @param array[] $aFullTokens List of full term tokens with the + * same name. + * + * @return SearchDescription[] List of derived search descriptions. + */ public function extendWithPartialTerm($aSearchTerm, $bStructuredPhrases, $iPhrase, &$aWordFrequencyScores, $aFullTokens) { // Only allow name terms. @@ -319,6 +412,23 @@ class SearchDescription /////////// Query functions + /** + * Query database for places that match this search. + * + * @param object $oDB Database connection to use. + * @param mixed[] $aWordFrequencyScores Number of times tokens appears + * overall in a planet database. + * @param mixed[] $aExactMatchCache Saves number of exact matches. + * @param integer $iMinRank Minimum address rank to restrict + * search to. + * @param integer $iMaxRank Maximum address rank to restrict + * search to. + * @param integer $iLimit Maximum number of results. + * + * @return mixed[] An array with two fields: IDs contains the list of + * matching place IDs and houseNumber the houseNumber + * if appicable or -1 if not. + */ public function query(&$oDB, &$aWordFrequencyScores, &$aExactMatchCache, $iMinRank, $iMaxRank, $iLimit) { $aPlaceIDs = array();