Understanding links in Luminesce query results

Many Luminesce provider columns know how to render their data in external applications (frequently but not always LUSID-Web). Query them and the values become links: select an instrument ID to open the instrument, a Scheduler-job-code to run the job, or a Drive-file-name to preview the file. The links follow your data through variables, joins, unions and views, so even your own complex queries, saved queries, Views and dashboards inherit these features.

What a link can do

Selecting a link does one of three things:

• Opens a LUSID dialog. In the Query Editor, the dialog opens in place, for example Edit Instrument or Run a job. Edit dialogs save real changes, just as they do elsewhere in the LUSID web app.

• Opens a page in the LUSID web app in a new tab, for example a portfolio's holdings dashboard, an integration run or a request log in Insights.

• Opens an external site in a new tab, or starts an email for a mailto: link.

The link text is always the cell's own value.

Where links come from

A provider declares links column by column. Each link is a template: an address with placeholders, such as {LusidInstrumentId}, that Luminesce fills in from the same row. You can see every template in the catalog:

select TableName, FieldName, ActionTemplate
from Sys.Field
where ActionTemplate is not null
order by TableName, FieldName

For example, the LusidInstrumentId column of Lusid.Instrument has this template:

/data-virtualisation/action-templates/instruments-edit?p1=LusidInstrumentId&p2={LusidInstrumentId}&p3={Scope}

It refers to two columns, LusidInstrumentId and Scope, so a row shows the link only when your query returns both. An address that starts with / is a page in the LUSID web app, and /data-virtualisation/action-templates/ addresses open a dialog. Any other address is an external https:, http: or mailto: link.

The appendix lists the links that come with Luminesce and LUSID. Your own views can add more; see How do I add links to a custom view?

How links follow your data

Luminesce works out where every result column came from. This is the same lineage that explains a calculated value in How do I see where a value in my results came from? A column that comes straight from a provider column keeps that column's link, however many steps lie in between.

Table variables

Links pass through table variables, including chains of them, and through server table variables (@!name) in later queries:

@bonds = select LusidInstrumentId, Scope, DisplayName, MaturityDate
from Lusid.Instrument.Bond;

@maturing = select * from @bonds
where MaturityDate < datetime('now', '+1 year');

select LusidInstrumentId, Scope, DisplayName, MaturityDate
from @maturing
order by MaturityDate

LusidInstrumentId still opens each bond, two variables later.

Joins

In a join, each column keeps the link of the provider it came from:

select t.TxnId, t.PortfolioScope, t.PortfolioCode,
       t.LusidInstrumentId, t.InstrumentScope, i.DisplayName, t.Units
from Lusid.Portfolio.Txn t
inner join Lusid.Instrument i
  on i.LusidInstrumentId = t.LusidInstrumentId
where t.PortfolioScope = 'Finbourne-Examples'
  and t.PortfolioCode = 'UK-Equities'

Here TxnId opens the transaction, PortfolioCode opens the portfolio, PortfolioScope opens the portfolio's holdings dashboard, and LusidInstrumentId opens the instrument.

Unions

A union takes its links from the first select. When every part reads the same kind of column, they all link:

select LusidInstrumentId, Scope, DisplayName from Lusid.Instrument.Bond
union all
select LusidInstrumentId, Scope, DisplayName from Lusid.Instrument.Equity

Views

A custom view passes on the links of the columns it returns unchanged, and can add links of its own. Querying the view gives the same links as querying the providers behind it. See How do I add links to a custom view?

What keeps a link, and what loses it

Renaming keeps the link on the renamed column, but the placeholders still refer to the original column names. If you rename a column that a link refers to, for example Scope as InstrumentScope, the row no longer has a Scope column, and the link disappears.

Seeing links

In the Query Editor

Links appear in the results grid, and also in Query History, saved queries, dashboards and the query preview. A link that opens a dialog opens it in place. Every other link opens a new tab.

The Query Editor shows links only when it asks for lineage. That's on by default. To check, navigate to Data Virtualisation > Settings and make sure Show query results lineage in editor is selected. Dashboards always show links.

Exported results contain the values only, not the links.

In LumiCode

LumiCode marks a value that has a link with ↗, in /rows, in the record view and in the transcript. Select it as you would any link in your terminal, often with Cmd or Ctrl held down. /transcript html keeps the links clickable, and the Markdown transcript writes them as Markdown links.

Every LumiCode link opens in your browser. A LUSID app link opens in the domain you're signed in to. A link to a dialog opens the dialog on its own page, which then tells you that you can close the tab.

LumiCode also needs lineage. If /set shows lineage off, run /set lineage on and run the query again.

When a link doesn't appear

A value shows as plain text, with no error, when:

• A column the link refers to isn't in your results. Check the template in Sys.Field and add every column it names, with its original name.

• One of those columns is empty on that row.

• The column is calculated. Return the column itself alongside your calculation.

• Lineage is turned off. See Seeing links.

• You don't have access to the feature the dialog belongs to. For example, the Edit order link needs access to order management.

• The provider doesn't have links.  Writer providers, such as usid.Portfolio.Txn.Writer, don't generally have them (by convention only and provider may have them), and many other providers don't have them yet, or have no user interface to link to.

• Luminesce rejected the link's address. Luminesce checks every link address when a provider or view is registered, and replaces an address it considers unsafe with *INVALID*, which never shows as a link.

Appendix: Provider columns with links

To show a link, a query must return the column itself and every column listed under Also return. New links are added regularly; Sys.Field always has the current list.

LUSID providers

Other providers

Related articles

• How do I add links to a custom view?

• How do I see where a value in my results came from?

• Understanding the Luminesce SQL query syntax