Runtime, publish, execute en logs

Versions tabel

• Version, Status, Published.
• Wheels (aantal dependency artifacts).
• Build (ms).

Endpoints en authenticatie

• trigger-Elements zijn one-shot handlers via POST /element/{elementId}.
• Elke request start een normale Element-run en eindigt zodra de entrypoint klaar is.
• server-Elements publiceren een ASGI/FastAPI-app via dezelfde gateway: /element/{elementId} en /element/{elementId}/{path...}.
• Server Element-paden kunnen HTTP requests, SSE streaming responses en WebSocket-verbindingen afhandelen. De runtime houdt de child server warm zolang er verkeer is en stopt hem na ongeveer 15 minuten idle; de volgende request start hem opnieuw.
• Gebruik een Access key als bearer token. De call draait als die gebruiker binnen de actieve tenantcontext en behoudt datasource- en forced-filterrechten.

Wanneer gebruik je dit?

• Gebruik dit als een Element tijdens de run al widget-data moet tonen of vervangen.
• Dit werkt via een datasource met connector type element en Default data format = Live stream, of direct via een gepubliceerd Element van type stream_data.
• De equivalente raw datasource config is dataFormat: "livestream". Legacy configs met streamMode: "commands" blijven ondersteund.

Belangrijke notities

• Deze helpers zijn bedoeld voor datasource requests via /data/{id}/livestream, niet voor gewone snapshot/parquet loads.
• Actieve dashboardfilters worden voor live-stream datasources standaard als params doorgestuurd naar het Element.
• Zet datasource requestParamsMode op none als je die filterparams juist niet wilt doorgeven.
• De normale return value van je Element blijft bestaan, maar live widget-updates horen uit deze stream helpers te komen.
• Gepubliceerde data- en stream_data-Elements zijn direct selecteerbaar als datasource in dashboards; een aparte datasource-doc is daarvoor niet verplicht.

Waar vind ik voorbeelden?

• element-examples/command_stream_demo.py toont incrementele row updates.
• element-examples/cloudrunlogs.py toont een langere append-only live tail.

Server Element requests

• HTTP/SSE requests via de publieke Element gateway maken execution logs met source=server_http nadat de response body klaar is.
• WebSocket-sessies maken een execution log met source=server_websocket wanneer de sessie sluit of faalt.
• Request logs bevatten method, path, query string, request id, status, duur en websocket message counts. Bodies en headers worden niet opgeslagen.

Logger-output tijdens runs

• Gebruik in Element-code de ingebouwde logger, bijvoorbeeld logger.info("Start refresh") of logger.error("API call mislukt").
• Deze berichten verschijnen in de uitvoerlogdetails per run, inclusief severity, loggernaam en stacktrace bij logger.exception(...).
• Gebruik dit voor controlepunten, externe API-fouten en business-validatie, zodat debugging niet alleen via stdout of traceback hoeft.

Integratie met datasources

• Element connector roept dezelfde runtime aan met elementId, elementVersion, elementEntrypoint.
• Request params kunnen direct worden doorgestuurd of hernoemd via requestParamMap.
• Timeouts zijn configureerbaar per datasource via elementTimeoutSeconds.

JSON payload voorbeelden

Test execution payload voor een gepubliceerd Element:

{
  "version": "v_20260605090000_abcd12",
  "timeoutSeconds": 3600,
  "params": {
    "country": "NL",
    "limit": 20
  }
}

Element-backed cached datasource payload:

{
  "id": "orders-from-element",
  "name": "Orders from Element",
  "type": "element",
  "dataFormat": "parquet-remote",
  "elementId": "el_orders",
  "elementVersion": "v_20260605090000_abcd12",
  "elementEntrypoint": "run",
  "includeRequestQueryParams": true
}

Live stream datasource payload:

{
  "id": "orders-live",
  "name": "Orders live",
  "type": "element",
  "elementId": "el_orders_live",
  "elementVersion": "v_20260605090000_abcd12",
  "elementEntrypoint": "run",
  "dataFormat": "livestream",
  "requestParamsMode": "filters"
}

Duurzame datasource writes

Gebruik appendDataSourceRows of dataSources.appendRows wanneer een Element rows blijvend moet opslaan in een uplink/parquet-backed datasource voor latere dashboards, queries of andere Elements.

def run():
    rows = [{
        "createdAt": "2026-06-05T12:00:00Z",
        "status": "ok",
        "value": 123,
    }]
    result = dataSources.appendRows("element_event_store", rows, merge=True)
    return {"inserted": result["inserted"]}

• Dit is iets anders dan live appendRows(); duurzame writes maken parquet parts via uplink.
• De helper is alleen beschikbaar wanneer de execution context datasource write capability geeft.
• Rows zijn append-only JSON-objecten en worden als batch verstuurd.
• Optionele meta kan uplink auto-create velden bevatten zoals dataSourceName, dataFormat, parquetPartitionColumn en parquetPartitionGranularity.

Runtime builtin function contracts

Import shims werken ook: from queryDataSources import queryDataSources, from query_datasources import query_datasources, import dataSources, from appendDataSourceRows import appendDataSourceRows, from askDashbot import askDashbot en import dashbot.

def run(context, params):
    answer = askDashbot(
        "Vat deze status samen in een zin.",
        allowTools=False,
        timeoutSeconds=3600
    )
    return {"summary": answer.text}

Lifecycle workflows

1. Maak of update de Element draft. Behoud source, dependencies, entrypoint en metadata fields die niet bij de wijziging horen.
2. Publish het Element en bewaar de teruggegeven version id.
3. Draai een kleine test execution payload. Bekijk execution logs bij import-, dependency-, timeout-, secret-, variable- of result-shape fouten.
4. Voor een Element-backed datasource maak of update je de datasource met type="element", elementId, elementVersion en elementEntrypoint="run".
5. Voor cached parquet zet je dataFormat="parquet-remote", queue je een parquet refresh en lees je de datasource flow totdat de terminal refresh event zichtbaar is.
6. Query de datasource en bind dashboard tables/filters alleen aan geverifieerde columns.

Veel voorkomende ongeldige payloads

• dataFormat="parquet" op een datasource die door parquetrefresh ververst moet worden. Gebruik parquet-remote of parquet-remote-view.
• Element datasource zonder gepubliceerde elementVersion.
• Draft source die de ingestelde entrypoint niet definieert.
• Hardcoded API keys, tokens of passwords in Element source. Gebruik runtime secrets.
• Live update code die yield gebruikt voor progress. Gebruik emitProgress, appendRows, replaceRows en clearRows.
• Live appendRows() gebruiken wanneer duurzame parquet opslag nodig is. Gebruik appendDataSourceRows() of dataSources.appendRows().
• yield en return <value> mixen in dezelfde entrypoint.

MCP tool names

• Runtime reference: get_element_runtime_contract, list_element_builtin_functions, get_element_builtin_function.
• Element lifecycle: validate_element, create_element, update_element, publish_element, run_element_test, list_element_execution_logs, read_element_execution_log.
• Runtime store: list_runtime_variables, set_runtime_variable, delete_runtime_variable, list_runtime_secrets, set_runtime_secret, delete_runtime_secret.
• Datasource verification: validate_datasource, create_datasource, update_datasource, refresh_datasource_parquet, list_datasource_flows, read_datasource_flow, run_datasource_query.
• Docs discovery: search_dashview_docs, resolve_dashview_doc_topic, read_dashview_doc_topic.

Backend API route references

• GET /elements, GET /elements/{element_id}, POST /elements, PUT /elements/{element_id}.
• POST /elements/{element_id}/publish, POST /elements/{element_id}/execute.
• GET /elements/{element_id}/execution-logs, GET /elements/{element_id}/execution-logs/{log_id}.
• GET /runtime-store/vars, PUT /runtime-store/vars/{variable_id}, GET /runtime-store/secrets, PUT /runtime-store/secrets/{secret_id}.
• POST /data-sources/{datasource_id}/parquet-refresh voor cached datasource refresh.

Gebruik de MCP Swagger helpers get_backend_api_summary, search_backend_api_endpoints en get_backend_api_endpoint voor raw backend calls.

LLM-oriented voorbeelden

# Before writing Element source through MCP:
runtime = get_element_runtime_contract()
query_helper = get_element_builtin_function("queryDataSources")
secret_helper = get_element_builtin_function("getSecret")

# Before guessing docs filenames:
doc = read_dashview_doc_topic("element-runtime-builtins")

# Before binding a table/filter:
rows = run_datasource_query(
  "select * from orders_from_element limit 20",
  sources=[{"dataSourceId": "orders_from_element"}],
  strict_sources=True,
  max_rows=20
)