Feat/index assets given a root node and/or depth

[Flix6x]

Description

• New field to fetch assets under some root node (including the root node)
• New field to fetch assets up to a certain tree depth:
  • 0: all top-level nodes (or just the root node, if specified)
  • 1: all top-level nodes and their children
  • if not specified, all decendants are included, presumably until you hit a db recursion limit
• Added missing field descriptions
• Added changelog item in documentation/changelog.rst
• Added changelog item in documentation/api/change_log.rst

Closes #1886

Look & Feel

How to test

• Use an asset with several generations of descendants (for instance, a simulation project)
• http://localhost:5000/api/v3_0/assets?root=<asset-id>&depth=1
• Try out different depths
• Try out leaving out any of the two new parameters

Further Improvements

• Discuss possible usage on asset listing. For instance, I'd suggest:
  • The asset listing under the main assets menu item shows all accessible assets
  • The asset listing on the account page shows only top-level assets (clicking on one of them will show its context page with all of its children) - this attempt at clearing up that listing seems related: feat: make listing public assets on account page optional #1872
• ui.views.assets.utils.get_list_assets_chart is a recursive function that might make use of the recursive CTE, but this is probably only worthwhile for large enough trees where we might notice a considerable delay (in loading the asset context page).
• Protection against cyclic relationships in what we assume to be a tree-like asset structures (also mentioned in Edit asset: set parent ID #1441 (comment)) (I'd prefer forbidding cyclic asset relationships altogether, over writing fail-safes against it.

Related Items

• I needed this for my work on the CEMS tutorial: Feat/CEMS tutorial flexmeasures-client#148
• A flexmeasures-client PR will follow

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #30832097 | 📁 Comparing e3cd324 against latest (ffffe01)

🔍 Preview build

Show files changed (7 files in total): 📝 7 modified | ➕ 0 added | ➖ 0 deleted

File	Status
changelog.html	📝 modified
genindex.html	📝 modified
http-routingtable.html	📝 modified
_autosummary/flexmeasures.api.v3_0.assets.html	📝 modified
_autosummary/flexmeasures.data.queries.generic_assets.html	📝 modified
api/change_log.html	📝 modified
api/v3_0.html	📝 modified

[nhoening]

I am trying this in Swagger, and it seems to me that this works, but only if I also set either the account_id (and it has to be the one of the root asset) or I set all_accessible to true.

Can you confirm that?

[Flix6x]

I am trying this in Swagger, and it seems to me that this works, but only if I also set either the account_id (and it has to be the one of the root asset) or I set all_accessible to true.

Can you confirm that?

No, I can't, although I did reproduce a situation that resembles your description. The all_accessible is False, by default, so if you query a root asset that is outside of your own account then you'll need to set the account_id for it to show up. On the other hand, if you query a root asset that lives in your own account, then I can get results regardless of whether or not account_id is filled in. Please confirm.

[nhoening]

The all_accessible is False, by default, so if you query a root asset that is outside of your own account then you'll need to set the account_id for it to show up.

Okay, thanks, I get it now.
My expectations as user were that the endpoint understands that I want this (sub)tree of assets, IF I can access it. I therefore suggest turning all_accessible to True if a root is given. It is in fact similar to giving an account ID, as both an account and a root asset represent the top of an asset tree (where the account is itself not an asset).
Or, alternatively, we could include root.owner in accounts (after running check_access(root.owner, "read")).

On the other hand, if you query a root asset that lives in your own account, then I can get results regardless of whether or not account_id is filled in. Please confirm.

I can confirm this works without an account_id.

[nhoening]

I tested this for a bit and I believe it does what is advertised.

I have a small questions, but we can also move on.

[nhoening]

Did you decide to turn use_all_accounts to True if root_asset is given (instead of only giving access to root_asset.owner), because some children might have a different owner than root_asset? I'm not sure that is possiblem just asking.

[Flix6x]

No, you are exactly right. So far we have always left open the possibility of having an asset tree with multiple owners involved. Although I have not entirely thought through its implications, I can imagine one might encounter the need in practice, perhaps involving chargers and EVs owned by different organisations, or a community asset (owned by some shared organisation) of (private) sites.