Data Engine

Ad-hoc SQL queries against organization data

Execute Data Engine SQL query

post

Run a read-only SQL query against the organization's data and return the resulting rows. Results are automatically scoped to the target organization, so do not add any organization filter yourself.

This endpoint is only available when the Data Engine feature is enabled for the server.

Use MySQL syntax for building SQL queries. Identifiers may be quoted with backticks; a reserved word used as a column name (e.g. value) must be quoted this way.

Limitations:

• Only a single read-only SELECT statement is allowed. INSERT, UPDATE, DELETE and any DDL are rejected. CTEs (WITH) and set operations (UNION, INTERSECT, EXCEPT) are allowed.

• Window functions (the OVER clause) are not supported.

• Only an allow-listed set of functions may be used; any other function is rejected:

  • Aggregates: COUNT, SUM, AVG, MIN, MAX, STDDEV, STDDEV_POP, STDDEV_SAMP, VARIANCE, VAR_POP, VAR_SAMP, BIT_AND, BIT_OR, BIT_XOR, ANY_VALUE, PERCENTILE_CONT, PERCENTILE_DISC.

  • Math: ABS, CEIL, CEILING, FLOOR, ROUND, TRUNCATE, MOD, POWER, SQRT, EXP, LN, LOG10, SIGN.

  • Date/time: EXTRACT, TIMESTAMPADD, TIMESTAMPDIFF, CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME, LOCALTIMESTAMP, LOCALTIME, NOW.

  • Conditional / null handling: COALESCE, NULLIF, IFNULL.

  • String: LOWER, UPPER, TRIM, LENGTH, CHAR_LENGTH, CHARACTER_LENGTH, SUBSTRING, CONCAT, REPLACE.

  • Type conversion: CAST.

• Standard query clauses (WHERE, GROUP BY, HAVING, ORDER BY, LIMIT/OFFSET), JOINs, CASE expressions, IN, and comparison/boolean/arithmetic operators are always allowed.

• A query returns at most 100000 rows and must finish within 30 seconds.

The response uses a compact representation: meta lists the result columns in order (each entry carries the column name), and rows holds one positional array of values per result row, aligned by index with the columns in meta.

Required permissions, when user-scoped authentication is used: QUERY_DATA_ENGINE.

Authorizations

bearerAuth

AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Body

application/json

sqlstringRequired

A single read-only SQL SELECT statement to run against the organization data.

Example: SELECT id, name FROM devices ORDER BY id ASC

orgIdinteger · int32Optional

Organization to run the query for. If not provided, the organization associated with the authentication token is used.

Example: 101

Responses

200

Query executed successfully

application/json

400

Bad request

application/json

403

User is missing the QUERY_DATA_ENGINE permission

application/json

404

Data Engine feature is disabled

application/json

429

Too many requests

500

Internal server error

application/json

post/api/v1/organization/data-engine/query

HTTPcURLJavaScriptPython

POST /api/v1/organization/data-engine/query HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "sql": "SELECT id, name FROM devices ORDER BY id ASC",
  "orgId": 101
}

{
  "meta": [
    {
      "name": "id"
    },
    {
      "name": "name"
    }
  ],
  "rows": [
    [
      101,
      "Sensor A"
    ],
    [
      102,
      "Sensor B"
    ]
  ]
}