> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/html-widget-developer-guide/data-engine.md).

# Data Engine

> Runs a read-only SQL query against your organization's Data Engine.

```js
bridge.executeDataEngineQuery(options)  // → Promise<DataEngineResult>
```

The query runs against your **organization's** data. The widget's bound device controls the request lifetime only — it does **not** scope the rows, and the call accepts no device or organization ID. SQL and server authorization decide what is readable.

**Parameters**

| Name             | Type     | Required | Description                                                                |
| ---------------- | -------- | -------- | -------------------------------------------------------------------------- |
| `options.sql`    | `string` | yes      | 1 to 5000 characters, not blank                                            |
| `options.limit`  | `number` | no       | Integer from 0 to 100000. **`0` (the default) means the server's row cap** |
| `options.offset` | `number` | no       | Integer from 0 to 2147483647. Default `0`                                  |

`options` must be a plain object with only these three properties, and the serialized request must not exceed 64 KB.

**Resolves with**

```ts
{
  meta:    Array<{ name: string }>,   // columns, in result order
  rows:    Array<Array<null | boolean | number | string | object | unknown[]>>,
  offset:  number,                    // echoes the request
  hasMore: boolean
}
```

Paginate with `nextOffset = result.offset + result.rows.length` while `hasMore` is `true`. Use a deterministic `ORDER BY` — each page is an independent query with no snapshot guarantee. There is no automatic refresh; run the query again when you need fresh rows.

**Rejects with**

| Code                     | When                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`        | `options` isn't an object, has an unknown property (`Unknown request property '<name>'`), `sql` isn't a string, or the request is too large |
| `invalid_options`        | `sql` is empty or too long, or `limit` / `offset` is out of range                                                                           |
| `invalid_selector`       | `limit` or `offset` isn't an integer                                                                                                        |
| `invalid_response`       | The host returned a malformed or mismatched result                                                                                          |
| `request_timeout`        | No result within 35 seconds                                                                                                                 |
| `too_many_requests`      | Too many queries pending at once                                                                                                            |
| `device_unavailable`     | The host doesn't provide Data Engine queries                                                                                                |
| `transport_disconnected` | The result couldn't be fetched                                                                                                              |
| `server_error`           | The query failed without a specific code; SQL error details may be in `details`                                                             |
| `bridge_destroyed`       | Called after `destroy()`                                                                                                                    |

**Permission:** `QUERY_DATA_ENGINE` (organization scope). The response must not exceed 5 MiB.

**Example**

```js
if (await bridge.isPermissionAllowed('QUERY_DATA_ENGINE').catch(() => false)) {
  const result = await bridge.executeDataEngineQuery({
    sql: 'SELECT ts, value FROM my_table ORDER BY ts DESC',
    limit: 500
  });
  renderTable(result.meta, result.rows);
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blynk.io/en/html-widget-developer-guide/data-engine.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
