]> git.openstreetmap.org Git - nominatim.git/blob - docs/library/Low-Level-DB-Access.md
rename documentation to 'Nominatim Manual'
[nominatim.git] / 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 data more directly. 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. The function returns a context manager. Use with a `with`
10 statement. This returns a `SearchConnection` object described below. 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