YAML configuration file
=======================

A single YAML file describes the document, the BO filters and the output column
typing. It is loaded by :func:`boapi.config.load_export_config` and consumed by
:func:`boapi.api.export_from_config`.

Full example
------------

.. literalinclude:: ../examples/s_lieuprel.yaml
   :language: yaml
   :caption: examples/s_lieuprel.yaml

Keys
----

``doc_id``
   Document identifier. A scalar value, or a mapping by environment
   (``qualif:`` / ``prod:``) resolved with the ``env`` argument.

``output``
   Output file path. The extension sets the format (``.parquet`` / ``.csv`` /
   ``.json``). The parent directory is created if needed.

``chunk_size``
   Number of rows per batch for the parquet export (bounded memory usage).

``dataprovider``
   Name of the dataprovider targeted by the filters.

``date_format``
   Default date format for ``datetime`` columns (overridden by ``format`` at
   the column level).

``filters``
   BO parameters, keyed by **parameter id** (see step 1). The value is a list
   of strings. Date bounds follow the format expected by BO, for example
   ``'2026-04-24T00:00:00.000Z'``.

``columns``
   Column typing and renaming. Columns not listed are kept as-is (pandas
   inference). Three forms:

   .. code-block:: yaml

      columns:
        id_lieu_prel: str                 # shorthand: type only
        lat: {type: float}
        date_prel: {rename: date_prelevement, type: datetime, format: "%d/%m/%Y"}

   Recognized types: ``str``, ``int``, ``float``, ``bool``, ``category``,
   ``datetime``.

Automatic generation
--------------------

The skeleton can be produced from a document with
:func:`boapi.api.generate_export_config` (or the
``examples/02_generate_config.py`` script):

.. code-block:: python

   from boapi import generate_export_config

   yaml_text = generate_export_config("123456", env="prod", with_columns=True)
   print(yaml_text)