more library documentation

docs/library/Input-Parameter-Types.md

@@ -1,28 +1,51 @@
-# Input parameters
+# Input Parameter Types
+
+This page describes in more detail some of the input parameter types used
+in the query functions of the API object.
 
 ## Place identification
 
+The [details](NominatimAPI.md#nominatim.api.core.NominatimAPI.details) and
+[lookup](NominatimAPI.md#nominatim.api.core.NominatimAPI.lookup) functions
+require references to places in the database. Below are listed the possible
+types for place identification. All types are dataclasses.
+
+### PlaceID
+
 ::: nominatim.api.PlaceID
     options:
         heading_level: 6
 
+### OsmID
+
 ::: nominatim.api.OsmID
     options:
         heading_level: 6
 
-## Geometries
+## Geometry types
 
 ::: nominatim.api.GeometryFormat
     options:
         heading_level: 6
+        members_order: source
+
+## Geometry input
+
+### Point
 
 ::: nominatim.api.Point
     options:
         heading_level: 6
+        show_signature_annotations: True
+
+### Bbox
 
 ::: nominatim.api.Bbox
     options:
         heading_level: 6
+        show_signature_annotations: True
+        members_order: source
+        group_by_category: False
 
 ## Layers
 

docs/library/Low-Level-DB-Access.md

@@ -1,5 +1,56 @@
 # Low-level connections
 
+The `NominatimAPIAsync` class allows to directly access the underlying
+database connection to explore the data more directly. Nominatim uses
+[SQLAlchemy](https://docs.sqlalchemy.org/) for building queries. Please
+refer to the documentation of the library to understand how to write SQL.
+
+To get access to a search connection, use the `begin()` function of your
+API object. The function returns a context manager. Use with a `with`
+statement. This returns a `SearchConnection` object described below. Its
+`t` property has definitions for all Nominatim search tables. For an
+overview of available tables, refer to the
+[Development Layout](../develop/Database-Layout.md) in in the development
+chapter. Note that only tables that are needed for search are accessible
+as SQLAlchemy tables.
+
+!!! warning
+    The database layout is not part of the API definition and may change
+    without notice. If you play with the low-level access functions, you
+    need to be prepared for such changes.
+
+Here is a simple example, which prints how many places are available in
+the placex table:
+
+```
+import asyncio
+from pathlib import Path
+import sqlalchemy as sa
+from nominatim.api import NominatimAPIAsync
+
+async def print_table_size():
+    api = NominatimAPIAsync(Path('.'))
+
+    async with api.begin() as conn:
+        cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))
+        print(f'placex table has {cnt} rows.')
+
+asyncio.run(print_table_size())
+```
+
+!!! warning
+    Low-level connections may only be used to read data from the database.
+    Do not use it to add or modify data or you might break Nominatim's
+    normal functions.
+
+## SearchConnection class
+
 ::: nominatim.api.SearchConnection
     options:
+        members:
+            - scalar
+            - execute
+            - get_class_table
+            - get_db_property
+            - get_property
         heading_level: 6

docs/library/Result-Handling.md

@@ -14,6 +14,10 @@
 
 ## Localization
 
+Results are always returned with the full list of available names.
+
+### Locale
+
 ::: nominatim.api.Locales
     options:
         heading_level: 6