Introduction to LumiCode

What is LumiCode?

LumiCode brings everything you do in Luminesce into a single interactive terminal tool: write SQL with full code completion, explore and chart the results, ask Candela, FINBOURNE's AI agent, for help, and diagnose failed queries without leaving the keyboard.

It is the Swiss Army knife for all things Luminesce: SQL, AI, diagnostics, data browsing and interpretation.

With LumiCode you can:

• Do most of what you can do in the Web Query Editor:
  • write SQL with syntax colouring, catalog-aware code completion and error highlighting (your catalog lists the providers available to you: anything that provides or manipulates data in Luminesce, including views, which are saved queries that appear in your catalog and behave like providers)
  • run queries as you develop and schedule them
  • view, browse and group results
  • chart results with advanced charting capabilities
  • see lineage visually (where the data in a query result really came from, through joins, views and even other providers), and use AI to explain it further
  • download results to your machine, or directly into Drive to share with others
  • create and run multi-queries (one run of several queries that may feed each other, and can be saved and exported together) to build complex datasets
• Reuse your most recently used (MRU) commands and SQL statements
• Get help from the integrated Candela AI, then run or edit its suggested queries in one step. It's especially good for:
  • improving your Luminesce queries
  • finding out how to get data out of anything in your provider catalog
• See your data in various ways:
  • tables
  • grouped tables / trees
  • a large number of charts
• Work directly with many other FINBOURNE services, such as:
  • Drive: browse it, and upload and download files
  • Configuration Service: view, create and modify config (needed for some provider setup)
  • Saved queries: create and run them, and browse the Workspaces they sit within
• View the history of everything you do in the FINBOURNE ecosystem:
  • Luminesce queries, API calls and access checks
  • everything you need to understand usage patterns, failures, etc.
• Download, install and update other Luminesce services:
  • Local File Providers
  • SQL DB providers
  • ODBC and Power BI drivers
• Use the special diagnose mode to understand query flows and error conditions
• Output your transcript (LumiCode's log of all the work you have done) as HTML or Markdown, for immediate re-use, presentations or consumption by AI
• ... and many, many other features (see LumiCode Commands)

Installing and updating

To install LumiCode, see How do I install LumiCode?.

It is a command-based system that self-updates and advertises its new features and improvements to you. After you first install it, LumiCode tells you when new features are available (unless you turn that off, of course) see /whats-new and /update.

Navigating your options

Every command, as well as the SQL editor, supports command completion.
So seeing a list of commands is as simple as typing / + Tab.
For example typing /help + Tab gives you this:

Writing SQL

Writing SQL works the way you'd expect: just start typing, press Tab if you are stuck and code completion will help you finish writing it or ask Candela to help out. You will see functions, providers, their fields and parameters, and code completion shows the documentation for each.

You can run more than one SQL statement at a time by putting a \ on its own line between them.

All SQL is executed and retrieved with the /api/SqlBackground API.

Links to reference documentation are likewise available:

You can always see what sort of SQL can follow beyond where your cursor lies ("code completion").

LumiCode shows progress as your query runs:

And you can get the full log into the transcript with /feedback.

Multi-queries

A multi-query is a set of possibly interrelated queries that you write in the SQL editor, then run and (optionally) export together.

Compared with separating statements with \, a multi-query lets you name each query, use one query's results in another, include saved queries, and export all the results and save the whole set together in a Workspace.

All SQL is executed and retrieved with the /api/MultiQueryBackground/custom API.

Write a multi-query like this:

• Each query starts with a header line --- @Name. Everything up to the next header is that query's SQL. Names start with a letter or _, contain only letters, digits and _, are at most 31 characters, and must be unique (case is ignored).
• One query reads another's results as @Name, the same way you'd use a table variable. A query can only read queries above it. Queries that read nothing start straight away, and any query that reads another waits for that one to finish.
• Add (internal) after the name for a query that only feeds the queries below it. Its results aren't shown alongside the others.
• Use --- @Name = {visibility}/{workspace}/items/{group}/{name} to include a saved query in the set. Nothing can be written under that line.
• Scalar parameters :name: can go anywhere a value can. All the queries in the set share them, so one value fills every :name: with that name.
• Not allowed: text above the first header, an empty query, and a \ separator line, because the headers already split the queries.

For example:

--- @Portfolios
select PortfolioScope, PortfolioCode, DisplayName, BaseCurrency
from Lusid.Portfolio
where PortfolioScope = :scope:'Finbourne-Examples'

--- @Instruments
select LusidInstrumentId, DisplayName, Isin
from Lusid.Instrument
where Isin is not null
limit 100

--- @Holdings
select p.PortfolioCode, p.DisplayName as Portfolio, h.LusidInstrumentId, h.Units
from @Portfolios p
inner join Lusid.Portfolio.Holding h
  on p.PortfolioScope = h.PortfolioScope
  and p.PortfolioCode = h.PortfolioCode
where h.EffectiveAt = :effectiveAt:#2026-09-30#

@Portfolios and @Instruments run at the same time; @Holdings waits for @Portfolios, then fetches holdings for just those portfolios.

Data rendered in tables, grouped tables and charts

LumiCode writes a summary of the results to the transcript:

Wherever you see data, if a provider (or a view you create!) supports links, LumiCode adds links that open other websites. This could open into LUSID, showing dialogs (Drive, LUSID-Instruments, Scheduler logs, Configuration Service entries, etc.) or any other site, such as Google Maps or your own internal systems.

/rows

/rows lets you explore all rows, further filter, choose columns, sort, and show detail cards (a panel showing every field of one row).

/group

Lets you group by any number of columns, expand them, apply group-aggregations, etc.

/chart

You can render the data as many types of chart, including into the transcript:

/chart gallery will show you examples of the full set, here's a small sample:

Using the built-in Candela AI

LumiCode natively uses Candela, FINBOURNE's AI agent. You can use it to ask about providers in your catalog, optimise queries, explain lineage of the data you are seeing and more.

Catalog browsing

/catalog gives you an interactive, searchable tree, including detail cards of providers/views, links to documentation, lineage, dependencies, uses of providers, etc.

Detail view

Lineage

You can see everything that depends on a provider / view:

... and everything that a view depends on:

View details

You can see many other view details, such as their definitions, the query that created them (so you can easily update them), etc.

History

Many forms of "user action history" are available in LumiCode.
You can query all of these through providers, but LumiCode also has simple commands with directed user interfaces to view this information. They all start with a time range first, so searches stay fast.

Query history

With /history you can search for queries with various SQL in them and limit to only failed ones. By default you see only your own queries. Users granted the GlobalMetadataVisibility activity on the Sys.Logs.HcQuery provider see queries from everyone in their domain (their organisation's LUSID environment).

API call history

With /api-history you can search for API calls for any FINBOURNE application in a given time range, limit to only failed ones (and filter by error message also). By default you see only your own calls; users granted the GlobalMetadataVisibility activity on the Lusid.Logs.AppRequest provider see calls from everyone in their domain.

Access check history

With /access-history you can search for access checks made by any application (or all of them). By default you see only your own access checks; users granted the Insights accesslogs-view-all permission see everyone's in their domain.

Failure diagnosis

With /diagnose <execution-id> or simply d from within the /history results you can initiate a process of deep investigation as to what took place when a given query ran (especially useful on failed queries). You'll find execution IDs in /history results and in LumiCode's output as queries run, among other places.

This will contain the SQL of the main query and all views that it may have used, details on errors, provider calls, the full user-feedback sent, etc.

This can generate a Markdown file useful for support or AI, looks for similar queries over time, etc.