Low-level connections

The NominatimAPIAsync class allows to directly access the underlying database connection to explore the raw data. Nominatim uses SQLAlchemy 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. This returns a SearchConnection object described below wrapped in a context manager. Its t property has definitions for all Nominatim search tables. For an overview of available tables, refer to the Development Layout 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

An extended SQLAlchemy connection class, that also contains then table definitions. The underlying asynchronous SQLAlchemy connection can be accessed with the 'connection' property. The 't' property is the collection of Nominatim tables.

scalar(sql, params=None) async

Execute a 'scalar()' query on the connection.

execute(sql, params=None) async

Execute a 'execute()' query on the connection.

get_class_table(cls, typ) async

Lookup up if there is a classtype table for the given category and return a SQLAlchemy table for it, if it exists.

get_db_property(name) async

Get a setting from the database. At the moment, only 'server_version', the version of the database software, can be retrieved with this function.

Raises a ValueError if the property does not exist.

get_property(name, cached=True) async

Get a property from Nominatim's property table.

Property values are normally cached so that they are only retrieved from the database when they are queried for the first time with this function. Set 'cached' to False to force reading the property from the database.

Raises a ValueError if the property does not exist.