sda.api.load_data_cloud
=======================

.. py:module:: sda.api.load_data_cloud

.. autoapi-nested-parse::

   Timeseries data loader that calls the SDA cloud ``/api/timeseries`` endpoint.

   Used as a fallback when no local PostgreSQL credentials are found in
   ``~/sda.json``.  Authentication uses the MSAL interactive / device-code flow
   (via :func:`sda.api.graph_auth.get_token_auto`) and the token is cached at
   ``~/.sda/token_cache.bin`` so the user only needs to log in once.

   To enable the cloud fallback, add ``SDA_CLOUD_URL`` to ``~/sda.json``::

       {
           "SDA_CLOUD_URL": "https://sda.example.com"
       }

   The environment variable ``SDA_CLOUD_URL`` is also accepted and takes
   precedence over the config file value.



Functions
---------

.. autoapisummary::

   sda.api.load_data_cloud.get_cloud_url
   sda.api.load_data_cloud.load_data_via_cloud


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

.. py:function:: get_cloud_url()

   Return the SDA cloud base URL, or ``None`` if not configured.

   Checks the ``SDA_CLOUD_URL`` environment variable first, then
   ``~/sda.json``.  Trailing slashes are stripped.


.. py:function:: load_data_via_cloud(tag, start_time = None, end_time = None)

   Load timeseries data by calling the SDA cloud ``/api/timeseries`` endpoint.

   Acquires a Microsoft access token via MSAL (silent refresh → browser
   popup → device-code flow).  The token is cached at
   ``~/.sda/token_cache.bin`` so the user only needs to log in once.

   :param tag: Test tag to query (e.g. ``gif1_t392``).  The same partial /
               case-insensitive matching logic as the direct DB path applies on the
               server side.
   :param start_time: Start of the time range (inclusive).  Forwarded as an ISO-8601 string.
   :param end_time: End of the time range (inclusive).  Forwarded as an ISO-8601 string.

   :returns: Wide DataFrame with a ``time`` column and one column per measurement,
             identical in structure to the direct-DB path.
   :rtype: :py:class:`pandas.DataFrame`

   :raises RuntimeError: If ``SDA_CLOUD_URL`` is not configured, authentication fails, or the
       HTTP request fails.
   :raises ValueError: If the SDA cloud reports that no tables were found for *tag*.