.. _oda_entities:

ODA Entities
=============

The ODA stores all of the data entities relevant to OSO. These top level entities are ``Proposal``, ``Panel``, ``Project``, ``SBDefinition``, ``SBInstance`` and ``ExecutionBlock``.

These entities are defined in the PDM, and more information can be found in the `PDM RTD <https://developer.skao.int/projects/ska-oso-pdm/en/latest/>`_

Status Entities
----------------

OSO entities have an associated state; for example, SBIs could be ``CREATED``, ``IN PROGRESS``, ``OBSERVED``, ``FAILED``. 
`ADR-41 <https://confluence.skatelescope.org/display/SWSI/ADR-41+Architectural+Location+for+Execution+Blocks>`_ formalises the relationship between entities and status entities, showing several data entities (projects, SBDs, SBIs, etc.) 
to have a 1:1 relationship with an associated status entity.

PostgreSQL Tables Structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Created separate tables for SBD, SBI and EB entities.

`For More Detailed info Click <https://confluence.skatelescope.org/pages/viewpage.action?pageId=267867440>`_


.. note::

    In status history tables composite key is combination of ``id``, ``entity_ref`` with ``{ENTITY_NAME}_version`` and ``current_status``.
    To allow duplicate values of ``id`` and ``entity_ref`` with ``{ENTITY_NAME}_version`` and ``current_status`` where ENTITY_NAME is eb, sbi, 
    sbd and prj

Curl APIs
~~~~~~~~~

For getting latest status history data from ODA Entities

.. code-block:: console

   $ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/<MAJOR_VERSION>/status/ebs/eb-mvp01-20240426-5781"

.. code-block:: console

   $ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/<MAJOR_VERSION>/status/sbis/sbi-mvp01-20240426-5782"

.. code-block:: console

   $ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/<MAJOR_VERSION>/status/sbds/sbd-mvp01-20240426-5783"

.. code-block:: console

   $ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/<MAJOR_VERSION>/status/prjs/prj-mvp01-20240426-5783"


For getting all status history data from ODA Entities

.. code-block:: console

   $ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/<MAJOR_VERSION>/status/history/ebs/eb-mvp01-20240426-5781"

.. code-block:: console

   $ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/<MAJOR_VERSION>/status/history/sbis/sbi-mvp01-20240426-5782"

.. code-block:: console
   
   $ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/<MAJOR_VERSION>/status/history/sbds/sbd-mvp01-20240426-5783"

.. code-block:: console
   
   $ curl -iX GET -H -d  "https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/<MAJOR_VERSION>/status/history/prjs/prj-mvp01-20240426-5783"


Entity Relationships
---------------------

The ODA provides a method to query entity relationships across the hierarchy.
Given any entity ID, it returns all related entity IDs (descendants for
prj/ob/sbd/sbi, or ancestors for eb) as flat lists grouped by entity type.

The entity hierarchy is::

    Project (prj)
      └─ Observing Block (ob)
           └─ SB Definition (sbd)
                └─ SB Instance (sbi)
                     └─ Execution Block (eb)

Relationships are resolved using the ``ltree`` path stored in
``status.latest_status_entries``, which encodes the full ancestor chain
for each entity.

Response Format
~~~~~~~~~~~~~~~~

For **prj, ob, sbd, sbi** (descendants as flat lists):

.. code-block:: json

   {
     "entity_id": "prj-cs7wrwvygpx",
     "entity_type": "prj",
     "related_entities": {
       "ob": ["ob-1"],
       "sbd": ["sbd-cs8175vyhaa", "sbd-ddzvmxnyg37"],
       "sbi": ["sbi-dd1fe2syhfk"],
       "eb": ["eb-de4qsnsyhet"]
     }
   }

For **eb** (single parent per level):

.. code-block:: json

   {
     "entity_id": "eb-de4qsnsyhet",
     "entity_type": "eb",
     "related_entities": {
       "prj": "prj-cs7wrwvygpx",
       "ob": "ob-1",
       "sbd": "sbd-ddzvmxnyg37",
       "sbi": "sbi-dd1fe2syhfk"
     }
   }

Keys in ``related_entities`` are only present when related entities exist.

Usage (via UnitOfWork)
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from ska_db_oda.unitofwork.postgresunitofwork import PostgresUnitOfWork

   with PostgresUnitOfWork() as uow:
       result = uow.entity_relationship.get_relationship("prj-cs7wrwvygpx")

The return type is ``EntityRelationship``, a Pydantic model defined in
``ska_db_oda.repository.domain.relationship``.