Ctrlk
GitHubBlynk WebsiteLogin to Blynk.Console
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Data Objects

Ad-hoc SQL queries against organization data

Execute Data Object 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 Objects 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.

Pass limit and offset to read the result one page at a time; the page is applied inside the query, so only those rows are produced. The response echoes offset and reports hasMore, which tells a pager whether another page follows.

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

Authorizations
AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Body
sqlstring · min: 1 · max: 1024Required

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
limitinteger · int32 · max: 100000Optional

Maximum number of rows to return. 0 (the default) returns as many rows as the 100000 row cap allows.

Default: 0Example: 50
offsetinteger · int64 · max: 2147483647Optional

Number of result rows to skip before the returned page starts.

Default: 0Example: 100
Responses
200

Query executed successfully

application/json
offsetinteger · int64Optional

Number of rows of the full result that precede the first returned row.

Example: 100
hasMorebooleanOptional

Whether the query had further rows beyond the returned ones — the next page, or the rows the 100000 row cap cut off.

Example: true
post/api/v1/organization/data-engine/query
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: 90

{
  "sql": "SELECT id, name FROM devices ORDER BY id ASC",
  "orgId": 101,
  "limit": 50,
  "offset": 100
}
{
  "meta": [
    {
      "name": "id"
    },
    {
      "name": "name"
    }
  ],
  "rows": [
    [
      101,
      "Sensor A"
    ],
    [
      102,
      "Sensor B"
    ]
  ],
  "offset": 100,
  "hasMore": true
}
PreviousOAuth
NextCustom Data

Last updated

Was this helpful?