bw_hestia_bridge.hestia_api.querying

Functions

get_hestia_node(→ dict)	Download the Hestia node associated to node.
get_node_type(→ str)	Get the node type from its Hestia ID
search_hestia(→ list[dict[str, str]])	Search the Hestia database.

Module Contents

bw_hestia_bridge.hestia_api.querying.get_hestia_node(node_id: str | dict[str, str], node_type: str | None = None, data_state: str | None = None, staging: bool | None = None) → dict

Download the Hestia node associated to node.

Parameters:

• node_id (str or dict[str, str]) – Hestia ID for the node or dictionary describing the node (e.g. returned from search_hestia()). If it’s a dict, it must contain at least an “@type” and an “@id” entry.

• node_type (str, optional (default: try to autodetect)) – 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”.

• data_state (str, optional (default: "recalculated")) – Version of the data, by default, use “recalculated” to download the more detailed version of the data. Use “original” to get the raw data.

• staging (bool, optional (default: from configuration)) – Whether to use the staging API.

Returns:

node – The dict associated to the JSON-LD entry describing node in the Hestia database.

Return type:

dict

bw_hestia_bridge.hestia_api.querying.get_node_type(node_id: str, staging: bool | None = None) → str

Get the node type from its Hestia ID

Parameters:

node_id (str) – Hestia ID for the node.

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.:

bw_hestia_bridge.hestia_api.querying.search_hestia(query: str | dict[str, str], node_type: str | None = None, fields: list[str] | None = None, limit: int | None = 10, how: Literal['or', 'and', 'exact'] = 'or', staging: bool | None = None) → list[dict[str, str]]

Search the Hestia database.

Parameters:

• query (str or dict) – 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.

• node_type (str, optional (default: any 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”.

• fields (list[str], optional (default: ["@type", "name", "@id"])) – Fields that will be returned in the search results.

• limit (int, optional (default: 10)) – The maximum number of results that will be returned (best match come first).

• how ({"or", "and", "exact"}, optional (default: "or")) – Whether the search tries to match any word in query (“or”), all words in query (“and”) or to match the whole query exactly (“exact”).

• staging (bool, optional (default: from configuration)) – Whether to use the staging API.

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”).

Return type:

list[dict]

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"})