epicsarchiver.retrieval.command
===============================

.. py:module:: epicsarchiver.retrieval.command

.. autoapi-nested-parse::

   Command module.



Attributes
----------

.. autoapisummary::

   epicsarchiver.retrieval.command.LOG
   epicsarchiver.retrieval.command.DATE_FORMATS


Functions
---------

.. autoapisummary::

   epicsarchiver.retrieval.command.get
   epicsarchiver.retrieval.command.export
   epicsarchiver.retrieval.command.read_pb
   epicsarchiver.retrieval.command.search
   epicsarchiver.retrieval.command._fetch_events
   epicsarchiver.retrieval.command._pv_name_search
   epicsarchiver.retrieval.command._fetch_raw_pb


Module Contents
---------------

.. py:data:: LOG
   :type:  logging.Logger

.. py:data:: DATE_FORMATS
   :value: ['%Y-%m-%d', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%d %H:%M:%S', '%Y-%m-%dT%H:%M:%S.%f', '%Y-%m-%d %H:%M:%S.%f']


.. py:function:: get(ctx: click.core.Context, pvs: tuple[str], start: datetime.datetime, end: datetime.datetime, processor_name: str | None, bin_size: int | None, debug: bool) -> None

   Print out data from an archiver cluster as a table.

   ARGUMENT pvs What pvs to get data of.

   Example usage:

   .. code-block:: console

       arch-retrieval --hostname archiver-01.example.com get PV_NAME1 PV_NAME2



.. py:function:: export(ctx: click.core.Context, pv: str, start: datetime.datetime, end: datetime.datetime, processor_name: str | None, bin_size: int | None, output_format: str, debug: bool) -> None

   Export PV data to stdout in a machine-readable format.

   ARGUMENT pv PV name to export data for.

   Example usage:

   .. code-block:: console

       arch-retrieval --hostname archiver.example.com export --format json MY_PV
       arch-retrieval --hostname archiver.example.com export --format pb MY_PV > out.pb

   :raises UsageError: When a polars-backed format is requested without the [polars] extra.


.. py:function:: read_pb(ctx: click.core.Context, file: str, debug: bool) -> None

   Display events from a local PB file.

   ARGUMENT file Path to the .pb file to read.

   Example usage:

   .. code-block:: console

       arch-retrieval read-pb MY_PV_2026.pb



.. py:function:: search(ctx: click.core.Context, query: str, start: datetime.datetime | None, end: datetime.datetime | None, limit: int, debug: bool) -> None

   Search for PV names using regex search patterns.

   Optionally specify start and/or end times to only return PVs that recorded data in
   the specified time range.

   ARGUMENT query PV name regex search pattern.

   Example usage:

   .. code-block:: console

       arch-retrieval --hostname archiver-01.example.com search                 "PBI-APTM02:Ctrl-ECAT-100:.*Temp1[2-4].*"

       arch-retrieval --hostname archiver-01.example.com search                 "PBI-APTM02:.*" -s "2026-01-06 02:50:00"

       arch-retrieval --hostname archiver-01.example.com search                 "(?i)mbl-060RFC:.*:tempambient" -s "2026-01-05"  -e "2026-01-06"



.. py:function:: _fetch_events(archiver: epicsarchiver.epicsarchiver.ArchiverAppliance, pvs: tuple[str, Ellipsis], start: datetime.datetime, end: datetime.datetime, processor: epicsarchiver.retrieval.client.processor.Processor | None) -> tuple[dict[int, epicsarchiver.retrieval.archive_event.ArchiveEventsMeta] | None, list[epicsarchiver.retrieval.archive_event.ArchiveEvent]]
   :async:


.. py:function:: _pv_name_search(archiver: epicsarchiver.epicsarchiver.ArchiverAppliance, query: str, start: datetime.datetime | None, end: datetime.datetime | None, limit: int) -> list[str]
   :async:


.. py:function:: _fetch_raw_pb(archiver: epicsarchiver.epicsarchiver.ArchiverAppliance, pv: str, start: datetime.datetime, end: datetime.datetime, processor: epicsarchiver.retrieval.client.processor.Processor | None = None, fetch_latest_metadata: bool = True) -> bytes
   :async: