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 import sqlalchemy as sa
  28 from nominatim_api import NominatimAPIAsync
  29
  30 async def print_table_size():
  31     api = NominatimAPIAsync()
  32
  33     async with api.begin() as conn:
  34         cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))
  35         print(f'placex table has {cnt} rows.')
  36
  37 asyncio.run(print_table_size())
  38 ```
  39
  40 !!! warning
  41     Low-level connections may only be used to read data from the database.
  42     Do not use it to add or modify data or you might break Nominatim's
  43     normal functions.
  44
  45 ## SearchConnection class
  46
  47 ::: nominatim_api.SearchConnection
  48     options:
  49         members:
  50             - scalar
  51             - execute
  52             - get_class_table
  53             - get_db_property
  54             - get_property
  55         heading_level: 6