.. _paramdb-label:

Parameter Database
==================

``pymetkit.paramdb`` maps between ECMWF short names, long names and numeric
parameter IDs. It is backed by a bundled ``parameter_metadata.json`` (with a
``parameter_metadata.yaml`` fallback loaded only when JSON is absent), or by the
live `ECMWF parameter database API <https://codes.ecmwf.int/parameter-database/>`__
in ``mode="online"``.

Usage
-----

.. code-block:: python

   from pymetkit.paramdb import ParamDB, AmbiguousParamError

   db = ParamDB()                        # mode="offline" by default; loads lazily

   db.shortname_to_param_id("msl")       # 151  — unambiguous
   db.param_id_to_shortname(151)         # "msl"
   db.shortname_to_longname("2t")        # "2 metre temperature"
   db.get_units(167)                     # "K"

Ambiguous short names
---------------------

Some short names map to more than one parameter ID (e.g. ``tp`` → ``228`` and
``228228``). ``ParamDB`` never guesses — an ambiguous lookup raises by default:

.. code-block:: python

   try:
       db.shortname_to_param_id("tp")
   except AmbiguousParamError as exc:
       for cand in exc.candidates:       # every ParamIDCandidate, sorted
           print(cand.param_id, cand.table)

Resolve the ambiguity in three ways:

.. code-block:: python

   # 1. Narrow with a MARS context (resolved via the C++ expand engine)
   db.shortname_to_param_id("tp", context={"class": "od"})   # 228

   # 2. Narrow with hard metadata filters (no MARS request constructed)
   db.shortname_to_param_id("tp", table=128)                 # 228

   # 3. Accept the canonical (first-sorted, lowest-table/id) candidate
   db.shortname_to_param_id("tp", default=True)              # 228

API reference
-------------

.. autoapiclass:: pymetkit.paramdb.ParamDB
   :members:

.. autoapiclass:: pymetkit.paramdb.ParamIDCandidate
   :members:

.. autoapiclass:: pymetkit.paramdb.ParameterEntry
   :members:

.. autoapiclass:: pymetkit.paramdb.MarsRequestContext
   :members:

.. autoapiexception:: pymetkit.paramdb.AmbiguousParamError
   :members:

.. _paramdb-regenerate:

Regenerating bundled metadata
------------------------------

The bundled files under ``share/metkit/`` are generated by fetching from the
ECMWF parameter database API. Run the generator script when the upstream database
changes:

.. code-block:: sh

   python -m pymetkit.paramdb.generate_metadata

This requires network access and the ``requests`` and ``pyyaml`` packages. It
writes the following files relative to the repository root:

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - File
     - Description
   * - ``share/metkit/parameter_metadata.json``
     - Compact JSON — preferred at runtime (~10–50× faster than YAML)
   * - ``share/metkit/parameter_metadata.yaml``
     - Human-readable YAML — fallback if JSON is absent
   * - ``share/metkit/unit_metadata.yaml``
     - Unit definitions
   * - ``share/metkit/parameter_entry_schema.json``
     - JSON Schema for ``ParameterEntry`` validation
   * - ``share/metkit/mars_context_schema.json``
     - JSON Schema for ``MarsRequestContext`` validation

The generator also enriches each entry with a ``table`` field (decoded from the
param ID encoding) and ``mars_request_context`` (inverted from
``share/metkit/params.yaml``) — both derived locally without additional network
access.

Commit the updated files to keep the bundled metadata in sync with the upstream
database.