Using getData() to Fetch Data

getData() is the primary way widgets retrieve data from connected data sources. It works with all four connection types: Tulip, SQL, MQTT, and Static.

Basic usage

In the JavaScript tab of the widget editor:

const data = await getData("My Connection");
console.log(data); // Array of row objects

getData() takes the name of a data connection (as configured in the widget's Data panel) and returns a promise that resolves to an array of objects. Each object represents one row, with keys matching the column/field names.

Example

Suppose you have a Tulip connection called "Production Orders" with fields order_id, status, and quantity:

const orders = await getData("Production Orders");

// orders looks like:
// [
//   { order_id: "ORD-001", status: "Complete", quantity: 50 },
//   { order_id: "ORD-002", status: "In Progress", quantity: 30 },
//   ...
// ]

const total = orders.reduce((sum, row) => sum + row.quantity, 0);
document.getElementById("total").textContent = total;

How it works by connection type

Type	Behavior
Tulip	Fetches records from the configured Tulip table, applying any filters and field selections. Results may come from cache if caching is enabled.
SQL	Executes the SQL query on the configured database and returns the result rows. Column labels are applied if configured.
MQTT	Returns the last received message value. For real-time updates, use onSourceData() instead (see below).
Static	Returns the embedded rows directly. No network request.

Real-time data with MQTT

For MQTT connections, getData() returns only the most recent message. To receive updates as they arrive, use onSourceData():

onSourceData("My MQTT Feed", (data) => {
  // Called each time a new message arrives on the topic
  document.getElementById("live-value").textContent = data.value;
});

onSourceData() returns an unsubscribe function if you need to stop listening.

Reading dashboard inputs

When a widget is placed on a dashboard, it can receive input values set by the user. Use getValue() to read them:

const selectedLine = getValue("production_line");

To react when an input changes:

window.addEventListener("inputchange", () => {
  const line = getValue("production_line");
  // Re-fetch or re-filter data based on the new value
});

See Widget Inputs and Dashboard Inputs for more on the input system.

Theme support

Widgets can adapt to the user's light or dark theme:

const theme = getTheme(); // "light" or "dark"

window.addEventListener("themechange", (e) => {
  const newTheme = e.detail; // "light" or "dark"
  // Update colors, chart styles, etc.
});

Available SDK functions

Function	Description
getData(connectionName)	Fetch data from a connected data source. Returns a Promise.
getValue(key)	Get the current value of a dashboard input.
setValue(key, value)	Set a dashboard input value (communicates to sibling widgets).
getTheme()	Get the current theme: "light" or "dark".
onSourceData(sourceName, handler)	Subscribe to real-time data from an MQTT connection. Returns an unsubscribe function.

Tips

• Always use await with getData(). The widget's JavaScript section runs inside an async wrapper, so await works at the top level.
• Connection names are case-sensitive. They must match exactly what you see in the Data panel.
• If getData() returns undefined or errors, check that the connection is properly configured and that the data source config is accessible to you. See Troubleshooting: Widget Issues.