Merge pull request #3587 from danieldegroot2/lookup-spelling

[nominatim.git] / docs / customize / Settings.md

diff --git a/docs/customize/Settings.md b/docs/customize/Settings.md
index f34f85b1f50b636ea735706f8d839c47aa6a5f17..b00d04cf6386bb3aa41b2d6f0409e0e043128239 100644 (file)
--- a/docs/customize/Settings.md
+++ b/docs/customize/Settings.md
@@ -57,41 +57,20 @@ parameter that is understood by libpq. See the [Postgres documentation](https://
 | **After Changes:** | cannot be changed after import |
 
 Defines the name of the database user that will run search queries. Usually
 | **After Changes:** | cannot be changed after import |
 
 Defines the name of the database user that will run search queries. Usually

-this is the user under which the webserver is executed. When running Nominatim
-via php-fpm, you can also define a separate query user. The Postgres user
+this is the user under which the webserver is executed. The Postgres user

 needs to be set up before starting the import.
 
 Nominatim grants minimal rights to this user to all tables that are needed
 for running geocoding queries.
 
 
 needs to be set up before starting the import.
 
 Nominatim grants minimal rights to this user to all tables that are needed
 for running geocoding queries.
 
 

-#### NOMINATIM_DATABASE_MODULE_PATH
-
-| Summary            |                                                     |
-| --------------     | --------------------------------------------------- |
-| **Description:**   | Directory where to find the PostgreSQL server module |
-| **Format:**        | path |
-| **Default:**       | _empty_ (use `<project_directory>/module`) |
-| **After Changes:** | run `nominatim refresh --functions` |
-| **Comment:**       | Legacy tokenizer only |
-
-Defines the directory in which the PostgreSQL server module `nominatim.so`
-is stored. The directory and module must be accessible by the PostgreSQL
-server.
-
-For information on how to use this setting when working with external databases,
-see [Advanced Installations](../admin/Advanced-Installations.md).
-
-The option is only used by the Legacy tokenizer and ignored otherwise.
-
-

 #### NOMINATIM_TOKENIZER
 
 | Summary            |                                                     |
 | --------------     | --------------------------------------------------- |
 | **Description:**   | Tokenizer used for normalizing and parsing queries and names |
 | **Format:**        | string |
 #### NOMINATIM_TOKENIZER
 
 | Summary            |                                                     |
 | --------------     | --------------------------------------------------- |
 | **Description:**   | Tokenizer used for normalizing and parsing queries and names |
 | **Format:**        | string |

-| **Default:**       | legacy |
+| **Default:**       | icu |

 | **After Changes:** | cannot be changed after import |
 
 Sets the tokenizer type to use for the import. For more information on
 | **After Changes:** | cannot be changed after import |
 
 Sets the tokenizer type to use for the import. For more information on


@@ -115,20 +94,6 @@ on the file format.
 If a relative path is given, then the file is searched first relative to the
 project directory and then in the global settings directory.
 
 If a relative path is given, then the file is searched first relative to the
 project directory and then in the global settings directory.
 

-#### NOMINATIM_MAX_WORD_FREQUENCY
-
-| Summary            |                                                     |
-| --------------     | --------------------------------------------------- |
-| **Description:**   | Number of occurrences before a word is considered frequent |
-| **Format:**        | int |
-| **Default:**       | 50000 |
-| **After Changes:** | cannot be changed after import |
-| **Comment:**       | Legacy tokenizer only |
-
-The word frequency count is used by the Legacy tokenizer to automatically
-identify _stop words_. Any partial term that occurs more often then what
-is defined in this setting, is effectively ignored during search.
-

 
 #### NOMINATIM_LIMIT_REINDEXING
 
 
 #### NOMINATIM_LIMIT_REINDEXING
 


@@ -163,25 +128,6 @@ codes, to restrict import to a subset of languages.
 Currently only affects the initial import of country names and special phrases.
 
 
 Currently only affects the initial import of country names and special phrases.
 
 

-#### NOMINATIM_TERM_NORMALIZATION
-
-| Summary            |                                                     |
-| --------------     | --------------------------------------------------- |
-| **Description:**   | Rules for normalizing terms for comparisons |
-| **Format:**        | string: semicolon-separated list of ICU rules |
-| **Default:**       | :: NFD (); [[:Nonspacing Mark:] [:Cf:]] >;  :: lower (); [[:Punctuation:][:Space:]]+ > ' '; :: NFC (); |
-| **Comment:**       | Legacy tokenizer only |
-
-[Special phrases](Special-Phrases.md) have stricter matching requirements than
-normal search terms. They must appear exactly in the query after this term
-normalization has been applied.
-
-Only has an effect on the Legacy tokenizer. For the ICU tokenizer the rules
-defined in the
-[normalization section](Tokenizers.md#normalization-and-transliteration)
-will be used.
-
-

 #### NOMINATIM_USE_US_TIGER_DATA
 
 | Summary            |                                                     |
 #### NOMINATIM_USE_US_TIGER_DATA
 
 | Summary            |                                                     |


@@ -189,7 +135,7 @@ will be used.
 | **Description:**   | Enable searching for Tiger house number data |
 | **Format:**        | boolean |
 | **Default:**       | no |
 | **Description:**   | Enable searching for Tiger house number data |
 | **Format:**        | boolean |
 | **Default:**       | no |

-| **After Changes:** | run `nominatim --refresh --functions` |
+| **After Changes:** | run `nominatim refresh --functions` |

 
 When this setting is enabled, search and reverse queries also take data
 from [Tiger house number data](Tiger.md) into account.
 
 When this setting is enabled, search and reverse queries also take data
 from [Tiger house number data](Tiger.md) into account.


@@ -202,7 +148,7 @@ from [Tiger house number data](Tiger.md) into account.
 | **Description:**   | Enable searching in external house number tables |
 | **Format:**        | boolean |
 | **Default:**       | no |
 | **Description:**   | Enable searching in external house number tables |
 | **Format:**        | boolean |
 | **Default:**       | no |

-| **After Changes:** | run `nominatim --refresh --functions` |
+| **After Changes:** | run `nominatim refresh --functions` |

 | **Comment:**       | Do not use. |
 
 When this setting is enabled, search queries also take data from external
 | **Comment:**       | Do not use. |
 
 When this setting is enabled, search queries also take data from external


@@ -309,12 +255,15 @@ unset, Nominatim expects the data to be saved in the project directory.
 | --------------     | --------------------------------------------------- |
 | **Description:**   | Configuration file for rank assignments |
 | **Format:**        | path |
 | --------------     | --------------------------------------------------- |
 | **Description:**   | Configuration file for rank assignments |
 | **Format:**        | path |

-| **Default:**       | _empty_ (use default settings) |
+| **Default:**       | address-levels.json |

 
 

-The _address level config_ configures rank assignments for places. See
+The _address level configuration_ defines the rank assignments for places. See

 [Place Ranking](Ranking.md) for a detailed explanation what rank assignments
 [Place Ranking](Ranking.md) for a detailed explanation what rank assignments

-are and what the configuration file must look like. The default configuration
-can be found in the configuration directory as `address-levels.json`.
+are and what the configuration file must look like.
+
+When a relative path is given, then the file is searched first relative to the
+project directory and then in the global settings directory.
+

 
 #### NOMINATIM_IMPORT_STYLE
 
 
 #### NOMINATIM_IMPORT_STYLE
 


@@ -325,9 +274,13 @@ can be found in the configuration directory as `address-levels.json`.
 | **Default:**       | extratags |
 
 The _style configuration_ describes which OSM objects and tags are taken
 | **Default:**       | extratags |
 
 The _style configuration_ describes which OSM objects and tags are taken

-into consideration for the search database. This setting may either
-be a string pointing to one of the internal styles or it may be a path
-pointing to a custom style.
+into consideration for the search database. Nominatim comes with a set
+of pre-configured styles, that may be configured here.
+
+You can also write your own custom style and point the setting to the file
+with the style. When a relative path is given, then the style file is searched
+first relative to the project directory and then in the global settings
+directory.

 
 See [Import Styles](Import-Styles.md)
 for more information on the available internal styles and the format of the
 
 See [Import Styles](Import-Styles.md)
 for more information on the available internal styles and the format of the


@@ -347,6 +300,9 @@ location for OSM nodes. For larger imports it can significantly speed up
 the import. When this option is unset, then osm2pgsql uses a PsotgreSQL table
 to store the locations.
 
 the import. When this option is unset, then osm2pgsql uses a PsotgreSQL table
 to store the locations.
 

+When a relative path is given, then the flatnode file is created/searched
+relative to the project directory.
+

 !!! warning
 
     The flatnode file is not only used during the initial import but also
 !!! warning
 
     The flatnode file is not only used during the initial import but also


@@ -534,35 +490,6 @@ the local languages (in OSM: the name tag without any language suffix) is
 used.
 
 
 used.
 
 

-#### NOMINATIM_SEARCH_BATCH_MODE
-
-| Summary            |                                                     |
-| --------------     | --------------------------------------------------- |
-| **Description:**   | Enable a special batch query mode |
-| **Format:**        | boolean |
-| **Default:**       | no |
-| **After Changes:** | run `nominatim refresh --website` |
-
-This feature is currently undocumented and potentially broken.
-
-
-#### NOMINATIM_SEARCH_NAME_ONLY_THRESHOLD
-
-| Summary            |                                                     |
-| --------------     | --------------------------------------------------- |
-| **Description:**   | Threshold for switching the search index lookup strategy |
-| **Format:**        | integer |
-| **Default:**       | 500 |
-| **After Changes:** | run `nominatim refresh --website` |
-
-This setting defines the threshold over which a name is no longer considered
-as rare. When searching for places with rare names, only the name is used
-for place lookups. Otherwise the name and any address information is used.
-
-This setting only has an effect after `nominatim refresh --word-counts` has
-been called to compute the word frequencies.
-
-

 #### NOMINATIM_LOOKUP_MAX_COUNT
 
 | Summary            |                                                     |
 #### NOMINATIM_LOOKUP_MAX_COUNT
 
 | Summary            |                                                     |


@@ -594,6 +521,87 @@ with a single query.
 
 Setting this parameter to 0 disables polygon output completely.
 
 
 Setting this parameter to 0 disables polygon output completely.
 

+
+#### NOMINATIM_SEARCH_WITHIN_COUNTRIES
+
+| Summary            |                                                     |
+| --------------     | --------------------------------------------------- |
+| **Description:**   | Disable search for elements that are not in the country grid |
+| **Format:**        | boolean |
+| **Default:**       | no |
+| **After Changes:** | run `nominatim refresh --website` |
+
+Enable to search elements just within countries.
+
+When enabled, if, despite not finding a point within the static grid of countries, it
+finds a geometry of a region, do not return the geometry.
+Return "Unable to geocode" instead.
+
+
+#### NOMINATIM_SERVE_LEGACY_URLS
+
+| Summary            |                                                     |
+| --------------     | --------------------------------------------------- |
+| **Description:**   | Enable serving via URLs with a .php suffix |
+| **Format:**        | boolean |
+| **Default:**       | yes |
+| **Comment:**       | Python frontend only |
+
+When enabled, then endpoints are reachable as `/<name>` as well as `/<name>.php`.
+This can be useful when you want to be backwards-compatible with previous
+versions of Nominatim.
+
+
+#### NOMINATIM_API_POOL_SIZE
+
+| Summary            |                                                     |
+| --------------     | --------------------------------------------------- |
+| **Description:**   | Number of parallel database connections per worker |
+| **Format:**        | number |
+| **Default:**       | 10 |
+| **Comment:**       | Python frontend only |
+
+Sets the maximum number of database connections available for a single instance
+of Nominatim. When configuring the maximum number of connections that your
+PostgreSQL database can handle, you need at least
+`NOMINATIM_API_POOL_SIZE` * `<number of configured workers>` connections.
+For configuring the number of workers, refer to the section about
+[Deploying the Python frontend](../admin/Deployment-Python.md).
+
+#### NOMINATIM_QUERY_TIMEOUT
+
+| Summary            |                                                     |
+| --------------     | --------------------------------------------------- |
+| **Description:**   | Timeout for SQL queries to the database |
+| **Format:**        | number (seconds) |
+| **Default:**       | 10 |
+| **Comment:**       | Python frontend only |
+
+When this timeout is set, then all SQL queries that run longer than the
+specified numbers of seconds will be cancelled and the user receives a
+timeout exceptions. Users of the API see a 503 HTTP error.
+
+The timeout does ont apply when using the
+[low-level DB access](../library/Low-Level-DB-Access.md)
+of the library. A timeout can be manually set, if required.
+
+
+#### NOMINATIM_REQUEST_TIMEOUT
+
+| Summary            |                                                     |
+| --------------     | --------------------------------------------------- |
+| **Description:**   | Timeout for search queries |
+| **Format:**        | number (seconds) |
+| **Default:**       | 60 |
+| **Comment:**       | Python frontend only |
+
+When this timeout is set, a search query will finish sending queries
+to the database after the timeout has passed and immediately return the
+results gathered so far.
+
+Note that under high load you may observe that users receive different results
+than usual without seeing an error. This may cause some confusion.
+

 ### Logging Settings
 
 #### NOMINATIM_LOG_DB
 ### Logging Settings
 
 #### NOMINATIM_LOG_DB


@@ -624,12 +632,34 @@ Can be used as the same time as NOMINATIM_LOG_FILE.
 | **After Changes:** | run `nominatim refresh --website` |
 
 Enable logging of requests into a file with this setting by setting the log
 | **After Changes:** | run `nominatim refresh --website` |
 
 Enable logging of requests into a file with this setting by setting the log

-file where to log to. The entries in the log file have the following format:
+file where to log to. A relative file name is assumed to be relative to
+the project directory.
+
+
+The entries in the log file have the following format:

 
     <request time> <execution time in s> <number of results> <type> "<query string>"
 
 Request time is the time when the request was started. The execution time is
 
     <request time> <execution time in s> <number of results> <type> "<query string>"
 
 Request time is the time when the request was started. The execution time is

-given in ms and corresponds to the time the query took executing in PHP.
+given in seconds and includes the entire time the query was queued and executed
+in the frontend.

 type contains the name of the endpoint used.
 
 Can be used as the same time as NOMINATIM_LOG_DB.
 type contains the name of the endpoint used.
 
 Can be used as the same time as NOMINATIM_LOG_DB.

+
+#### NOMINATIM_DEBUG_SQL
+
+| Summary            |                                                     |
+| --------------     | --------------------------------------------------- |
+| **Description:**   | Enable printing of raw SQL by SQLAlchemy |
+| **Format:**        | boolean |
+| **Default:**       | no |
+| **Comment:**       | **For developers only.** |
+
+This settings enables
+[SQL debugging](https://docs.sqlalchemy.org/en/20/core/engines.html#dbengine-logging)
+by SQLAlchemy. This can be helpful when debugging some bugs with internal
+query handling. It should only be used together with the CLI query functions.
+Enabling it for server mode may have unintended consequences. Use the `debug`
+parameter instead, which prints information on how the search is executed
+including SQL statements.