How to properly pass field names/titles from datasource plugin

Hi there! We encountered an issue with passing field names from a datasource plugin, which is documented here: Setting of config.displayName appears to clash with Grafana handling of displayName · Issue #53 · fifemon/graphql-datasource · GitHub. It boils down to a lack of clarity (or understanding) about how exactly the field name/title/label should be passed by the datasource. There appear to be at least three options:

  1. fields[..].name
  2. fields[..].config.displayName
  3. fields[..].config.displayNameFromDS

Based on the (not so clear) discussion in this PR, I was left with the impression that displayNameFromDS would be the correct way to go. But in actual implementation, both options (2) and (3) lead to undesirable results when an Outer Join transformation is applied (see Missing columns in Organize Fields transformation after Outer Join (New in 7.4) · Issue #31104 · grafana/grafana · GitHub). I.e., it appears that setting either config.displayName or config.displayNameFromDS interferes with Grafana’s subsequent handling of field names.

All in all, can anyone confirm that option (1) - i.e. setting fields[..].name - is the correct approach for setting a title? And under what circumstances should the other approaches be used? This feels like an important interface to get right.

My experience is that displayNameFromDS is mainly used when a data frame returns multiple fields, to denote a “primary” field. For example, in the case of a time series, the data frame could contain two fields, Time and Value, where Value is considered the primary metric and instead of just displaying “Value”, you want to display the name of the time series itself.

I haven’t seen field.config.displayName used before, but my guess is that it’s a property set by Grafana rather than the plugin author. I could be wrong though.

I had this confirmed by the team. field.config.displayNameFromDS is only used for data sources that return frame names and labels, to override Grafana’s built-in frame name/field label naming system. For example Prometheus and Graphite.

Ok, thanks @marcusolsson. I think that mostly makes sense. Where things get a bit muddled (for me), is that for example setting config.displayNameFromDS seems to conflict with Grafana’s subsequent handling of series names, leading to issues like Missing columns in Organize Fields transformation after Outer Join (New in 7.4) · Issue #31104 · grafana/grafana · GitHub. Though I suppose you could legitimately say “well, you wanted it to be overridden so now it’s overridden, and yes there may be side effects”.

Anyway, is it correct to take away that setting fields[..].name should be the “standard” way to set a series title, and that config.displayNameFromDS shouldn’t be touched unless a special override is necessary?