bw_hestia_bridge.hestia_api.querying
====================================

.. py:module:: bw_hestia_bridge.hestia_api.querying


Functions
---------

.. autoapisummary::

   bw_hestia_bridge.hestia_api.querying.get_hestia_node
   bw_hestia_bridge.hestia_api.querying.get_node_type
   bw_hestia_bridge.hestia_api.querying.search_hestia


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

.. py:function:: get_hestia_node(node_id: Union[str, dict[str, str]], node_type: Optional[str] = None, data_state: Optional[str] = None, staging: Optional[bool] = None) -> dict

   Download the Hestia node associated to `node`.

   :param node_id: Hestia ID for the node or dictionary describing the node (e.g. returned from
                   :func:`search_hestia`). If it's a dict, it must contain at least an "@type"
                   and an "@id" entry.
   :type node_id: str or dict[str, str]
   :param node_type: A valid type among "actor", "animal", "bibliography", "completeness",
                     "cycle", "emission", "impactassessment", "indicator",
                     "infrastructure", "input", "management", "measurement",
                     "organisation", "practice", "product", "property", "site", "source",
                     "term", "transformation", or "transport". If not provided, will either
                     be taken from `node_id` if it is a dict, or default to "cycle".
   :type node_type: str, optional (default: try to autodetect)
   :param data_state: Version of the data, by default, use "recalculated" to download the
                      more detailed version of the data. Use "original" to get the raw data.
   :type data_state: str, optional (default: "recalculated")
   :param staging: Whether to use the staging API.
   :type staging: bool, optional (default: from configuration)

   :returns: **node** -- The dict associated to the JSON-LD entry describing `node` in the
             Hestia database.
   :rtype: dict


.. py:function:: get_node_type(node_id: str, staging: Optional[bool] = None) -> str

   Get the node type from its Hestia ID

   :param node_id: Hestia ID for the node.
   :type node_id: str

   :returns: * **node_type** (*str*) -- The type of the node.
             * **staging** (*bool, optional (default: from configuration)*) -- Whether to use the staging API.

   :raises ValueError : if `node_id` is not found.:


.. py:function:: search_hestia(query: Union[str, dict[str, str]], node_type: Optional[str] = None, fields: Optional[list[str]] = None, limit: Optional[int] = 10, how: Literal['or', 'and', 'exact'] = 'or', staging: Optional[bool] = None) -> list[dict[str, str]]

   Search the Hestia database.

   :param query: A string to match to names in the Hestia database, or a dict of the
                 form ``{"field_name": value}`` to match `field_name` instead of
                 "name". See the examples below to see how to make more complex
                 quieries.
   :type query: str or dict
   :param node_type: A valid type among "actor", "animal", "bibliography", "completeness",
                     "cycle", "emission", "impactassessment", "indicator",
                     "infrastructure", "input", "management", "measurement",
                     "organisation", "practice", "product", "property", "site", "source",
                     "term", "transformation", or "transport".
   :type node_type: str, optional (default: any type)
   :param fields: Fields that will be returned in the search results.
   :type fields: list[str], optional (default: ["@type", "name", "@id"])
   :param limit: The maximum number of results that will be returned (best match come
                 first).
   :type limit: int, optional (default: 10)
   :param how: Whether the search tries to match any word in `query` ("or"), all
               words in `query` ("and") or to match the whole query exactly
               ("exact").
   :type how: {"or", "and", "exact"}, optional (default: "or")
   :param staging: Whether to use the staging API.
   :type staging: bool, optional (default: from configuration)

   :returns: **res** -- A list of dicts containing the `fields` entries. Additionally, a
             "_score" value is returned, indicating the accuracy of the match found
             in the Hestia database (results are sorted by decreasing "_score").
   :rtype: list[dict]

   .. rubric:: Examples

   One can refine the query by searching for nodes that have a product with a
   name matching "Saplings" by using ::

       search_hestia({"products.term.name": "Saplings"})

   It is also possible to do multi-criteria searches as follow ::

       search_hestia({"name": "Ouidah", "products.term.name": "Saplings"})