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

   1 # Low-level connections
   2
   3 The `NominatimAPIAsync` class allows to directly access the underlying
   4 database connection to explore the raw data. Nominatim uses
   5 [SQLAlchemy](https://docs.sqlalchemy.org/) for building queries. Please
   6 refer to the documentation of the library to understand how to write SQL.
   7
   8 To get access to a search connection, use the `begin()` function of your
   9 API object. This returns a `SearchConnection` object described below
  10 wrapped in a context manager. Its
  11 `t` property has definitions for all Nominatim search tables. For an
  12 overview of available tables, refer to the
  13 [Development Layout](../develop/Database-Layout.md) in in the development
  14 chapter. Note that only tables that are needed for search are accessible
  15 as SQLAlchemy tables.
  16
  17 !!! warning
  18     The database layout is not part of the API definition and may change
  19     without notice. If you play with the low-level access functions, you
  20     need to be prepared for such changes.
  21
  22 Here is a simple example, which prints how many places are available in
  23 the placex table:
  24
  25 ```
  26 import asyncio
  27 from pathlib import Path
  28 import sqlalchemy as sa
  29 from nominatim_api import NominatimAPIAsync
  30
  31 async def print_table_size():
  32     api = NominatimAPIAsync(Path('.'))
  33
  34     async with api.begin() as conn:
  35         cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))
  36         print(f'placex table has {cnt} rows.')
  37
  38 asyncio.run(print_table_size())
  39 ```
  40
  41 !!! warning
  42     Low-level connections may only be used to read data from the database.
  43     Do not use it to add or modify data or you might break Nominatim's
  44     normal functions.
  45
  46 ## SearchConnection class
  47
  48 ::: nominatim_api.SearchConnection
  49     options:
  50         members:
  51             - scalar
  52             - execute
  53             - get_class_table
  54             - get_db_property
  55             - get_property
  56         heading_level: 6