Elements runtime reference / Datasource access

`queryDataSources`

Run DuckDB SQL against Dashview datasources from inside an Element under the current execution access context.

Terug naar builtin index Signatuur Payloadformaat Voorbeeld Scope-notities

Signatuur

queryDataSources(sql, sources=None, includeAllDatasources=None, allowAgentsOnly=False, strictSources=None, maxRows=None, timeoutSeconds=None, backendBaseUrl=None, asTable=None, table=None, tableName=None)

Doel

Run DuckDB SQL against Dashview datasources from inside an Element under the current execution access context.

Aliases and imports

query_datasources
dataSources.query
dataSources.query_rows

Payloadformaat

Use these fields as the Python call arguments or keyword payload for this helper.

{
  "sql": "SELECT status, count(*) AS rows FROM \"orders\" GROUP BY status",
  "sources": [
    {
      "dataSourceId": "orders"
    }
  ],
  "maxRows": 5000,
  "strictSources": true,
  "asTable": "orders_summary"
}

Field	Description
`sql`	SQL string. Use datasource IDs as table names unless an explicit source alias is configured.
`sources`	Optional list of datasource bindings such as {'dataSourceId': 'orders'} or {'alias': 'orders', 'dataSourceId': 'orders'}.
`includeAllDatasources`	Optional bool. Leave false unless intentionally querying all available datasources.
`allowAgentsOnly`	Optional bool for agent-only datasource access behavior.
`strictSources`	Optional bool. Keep true when validating a specific dashboard or datasource binding.
`maxRows`	Optional row cap for the query result.
`timeoutSeconds`	Optional per-query timeout.
`backendBaseUrl`	Optional override; normally leave unset.
`asTable/table/tableName`	Optional safe SQL identifier. When set, the result is loaded into the Element-local DuckDB connection under that table name.

Return payload

{
  "rows": [
    {
      "status": "open",
      "rows": 42
    }
  ],
  "columns": [
    {
      "name": "status",
      "type": "string"
    },
    {
      "name": "rows",
      "type": "integer"
    }
  ],
  "rowCount": 1,
  "table": "orders_summary",
  "artifact": {
    "kind": "parquet",
    "format": "parquet",
    "path": "/tmp/.../result.parquet"
  }
}

Voorbeeld

def run(duckdb):
    result = queryDataSources(
        'SELECT status, count(*) AS rows FROM "orders" GROUP BY status',
        sources=[{"dataSourceId": "orders"}],
        asTable="orders_summary",
    )
    duckdb.execute("CREATE TABLE output AS SELECT * FROM orders_summary")
    return {"table": "output"}

Scope-notities

The helper forwards the execution access context and reuses backend/data-worker-agent permission checks and forced filters.
Use explicit sources when validating a dashboard binding or restricting which datasources may load.
With asTable/table/tableName, returned rows is empty or bounded because data stays on the parquet/DuckDB path; read the loaded table through duckdb.
The asTable/table/tableName value must be a safe SQL identifier.

queryDataSources