Elements runtime reference

Element runtime builtin functies

Gebruik deze pagina als index voor de ingebouwde Element runtime helpers. Elke helper heeft een eigen contractpagina met signature, payloadvelden, return shape, voorbeeldcode en scope-notities.

Contractpagina's Scope-notities Import shims Local SQL Datasource access Request artifacts Tenant GCS files AI and delivery Runtime store Live streaming Side effects Diagnostics

Element runtime testdialoog met parameters en uitvoer — Test een Element in de actuele runtime voordat je het in een dashboard of workflow gebruikt.

Contractpagina's

Helper	Groep	Samenvatting	Signatuur
`duckdb`	Local SQL	Use the Element request-local DuckDB connection for local SQL, joins, dataframe registration, and table-shaped Element output.	def run(..., duckdb): duckdb.execute(sql, parameters=None)
`queryDataSources`	Datasource access	Run DuckDB SQL against Dashview datasources from inside an Element under the current execution access context.	queryDataSources(sql, sources=None, includeAllDatasources=None, allowAgentsOnly=False, strictSources=None, maxRows=None, timeoutSeconds=None, backendBaseUrl=None, asTable=None, table=None, tableName=None)
`appendDataSourceRows`	Datasource access	Durably append JSON rows from an Element into an uplink/parquet-backed datasource.	appendDataSourceRows(dataSourceId, rows=None, merge=None, forcedFilterHash=None, meta=None, timeoutSeconds=None, idempotencyKey=None)
`writeFile`	Request artifacts	Write a request-scoped Element artifact file through the parent data-worker-agent process.	writeFile(path, content=None, data=None, dataBase64=None, rows=None, format=None, bucket=None, prefix=None, contentType=None, encoding=None, overwrite=False, metadata=None)
`readFile`	Request artifacts	Read a request-scoped Element artifact file visible to the current run.	readFile(path, bucket=None, prefix=None, encoding='utf-8', asBytes=False, maxBytes=None, withMetadata=False)
`listFiles`	Request artifacts	List request-scoped Element artifact files.	listFiles(prefix=None, bucket=None, maxResults=None, withMetadata=False)
`uploadGcsFile`	Tenant GCS files	Upload a tenant-scoped file from an Element into the configured GCS file artifact/output bucket.	uploadGcsFile(path, content=None, data=None, dataBase64=None, rows=None, format=None, bucket=None, prefix=None, contentType=None, encoding=None, overwrite=False, metadata=None, signedUrl=False, ttlSeconds=None, method=None)
`downloadGcsFile`	Tenant GCS files	Read a tenant-scoped GCS file through data-worker-agent.	downloadGcsFile(path, bucket=None, prefix=None, encoding='utf-8', asBytes=False, maxBytes=None, withMetadata=False)
`signGcsFile`	Tenant GCS files	Generate a short-lived signed URL for a tenant-scoped GCS object.	signGcsFile(path, bucket=None, prefix=None, ttlSeconds=None, method='GET', contentType=None)
`listGcsFiles`	Tenant GCS files	List tenant-scoped GCS files under the current tenant folder.	listGcsFiles(prefix=None, bucket=None, maxResults=None, withMetadata=False)
`deleteGcsFile`	Tenant GCS files	Delete a tenant-scoped GCS object from inside an Element.	deleteGcsFile(path, bucket=None, prefix=None, ignoreMissing=False)
`askDashbot`	AI and delivery	Call Dashbot from inside an Element and read the answer under the execution access context.	askDashbot(prompt, responseFormat=None, allowTools=None, maxToolCalls=None, toolScope=None, contextId=None, timeoutSeconds=None, language=None, timeZone=None, localNow=None, localDate=None)
`sendEmail`	AI and delivery	Send tenant-scoped email through data-worker-agent and notification-delivery without exposing email credentials to Element code.	sendEmail(payload=None, **kwargs) / send_email(to=None, subject=None, body=None, html_body=None, template_key=None, template_context=None, recipients=None, recipient_uids=None, data=None, attachments=None, persist_notification=None, idempotency_key=None, timeout_seconds=None)
`getVar`	Runtime store	Read the current tenant-shared runtime variable value by id.	getVar(name, default=None)
`setVar`	Runtime store	Persist a tenant-shared runtime variable immediately during Element execution.	setVar(name, value=None)
`getSecret`	Runtime store	Read a tenant-shared runtime secret by id during Element execution.	getSecret(name, default=None)
`emitProgress`	Live streaming	Emit a live progress/status event during ExecuteStream runs.	emitProgress(payload=None, **kwargs)
`appendRows`	Live streaming	Append rows to a live command-stream datasource while the Element is still running.	appendRows(rows=None, **kwargs)
`replaceRows`	Live streaming	Replace the current live command-stream datasource rows.	replaceRows(rows=None, **kwargs)
`clearRows`	Live streaming	Clear the current live command-stream datasource rows.	clearRows(payload=None, **kwargs)
`createNotification`	Side effects	Append a notification side effect to Element runtime output.	createNotification(payload=None, **kwargs)
`createTask`	Side effects	Append a task side effect to Element runtime output.	createTask(payload=None, **kwargs)
`timeBlock`	Diagnostics	Record helper timing metadata for named code blocks.	timeBlock(name) / measureTime(name, func, args, *kwargs)
`logger`	Diagnostics	Write structured Element execution diagnostics captured in execution log details.	logger.info(message, args, kwargs) / logger.exception(message, args, **kwargs)

Local SQL

duckdb - Use the Element request-local DuckDB connection for local SQL, joins, dataframe registration, and table-shaped Element output.

Datasource access

queryDataSources - Run DuckDB SQL against Dashview datasources from inside an Element under the current execution access context.
appendDataSourceRows - Durably append JSON rows from an Element into an uplink/parquet-backed datasource.

Request artifacts

writeFile - Write a request-scoped Element artifact file through the parent data-worker-agent process.
readFile - Read a request-scoped Element artifact file visible to the current run.
listFiles - List request-scoped Element artifact files.

Tenant GCS files

uploadGcsFile - Upload a tenant-scoped file from an Element into the configured GCS file artifact/output bucket.
downloadGcsFile - Read a tenant-scoped GCS file through data-worker-agent.
signGcsFile - Generate a short-lived signed URL for a tenant-scoped GCS object.
listGcsFiles - List tenant-scoped GCS files under the current tenant folder.
deleteGcsFile - Delete a tenant-scoped GCS object from inside an Element.

AI and delivery

askDashbot - Call Dashbot from inside an Element and read the answer under the execution access context.
sendEmail - Send tenant-scoped email through data-worker-agent and notification-delivery without exposing email credentials to Element code.

Runtime store

getVar - Read the current tenant-shared runtime variable value by id.
setVar - Persist a tenant-shared runtime variable immediately during Element execution.
getSecret - Read a tenant-shared runtime secret by id during Element execution.

Live streaming

emitProgress - Emit a live progress/status event during ExecuteStream runs.
appendRows - Append rows to a live command-stream datasource while the Element is still running.
replaceRows - Replace the current live command-stream datasource rows.
clearRows - Clear the current live command-stream datasource rows.

Side effects

createNotification - Append a notification side effect to Element runtime output.
createTask - Append a task side effect to Element runtime output.

Diagnostics

timeBlock - Record helper timing metadata for named code blocks.
logger - Write structured Element execution diagnostics captured in execution log details.

Scope and access context

Runtime helpers execute inside the Element runtime but sensitive actions are still scoped by Dashview services. Datasource reads forward the execution access context and keep tenant, user, datasource, and forced-filter checks in place. File helpers are constrained to request artifact prefixes or the current tenant filestore prefix.

Element code cannot mint broader access by passing tenant, user, bucket, datasource, or recipient fields in a payload. Treat signed URLs, secrets, and email recipients as sensitive runtime data.

Import shims

Helpers are injected as globals. These optional import shims also work inside Dashview-run Elements:

from queryDataSources import queryDataSources
from query_datasources import query_datasources
import dataSources
from appendDataSourceRows import appendDataSourceRows
import files
from writeFile import writeFile
from readFile import readFile
from listFiles import listFiles
from gcs import gcs
from uploadGcsFile import uploadGcsFile
from askDashbot import askDashbot
import dashbot
from sendEmail import sendEmail
from send_email import send_email
from mail import send