> 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/blynk.cloud/platform-https-api/data-objects.md).
# Data Objects
Ad-hoc SQL queries against organization data
## Execute Data Object SQL query
> 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.\
> \- JSON: JSON\_VALUE, JSON\_QUERY, JSON\_EXISTS, JSON\_TYPE, JSON\_DEPTH, JSON\_LENGTH,\
> JSON\_KEYS, JSON\_PRETTY.\
> \- 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 column holding JSON (e.g. \`device\_metadata\_values.value\_json\`) is read with the JSON\
> functions: JSON\_VALUE(value\_json, '$.value') extracts a scalar as a string, and\
> JSON\_QUERY(value\_json, '$.tags') extracts a nested object or array. CAST the extracted\
> value to compare or aggregate it as a number, filtering out the rows that do not hold\
> one. A path that matches nothing gives NULL for JSON\_VALUE and JSON\_QUERY and FALSE for\
> JSON\_EXISTS, but is an error for JSON\_LENGTH and JSON\_KEYS unless it is prefixed with\
> 'lax' (e.g. 'lax $.tags').\
> \* 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\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Data Objects","description":"Ad-hoc SQL queries against organization data"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/data-engine/query":{"post":{"tags":["Data Objects"],"summary":"Execute Data Object SQL query","description":"Run a read-only SQL query against the organization's data and return the resulting rows.\nResults are automatically scoped to the target organization, so do not add any organization\nfilter yourself.\n\nThis endpoint is only available when the Data Objects feature is enabled for the server.\n\nUse MySQL syntax for building SQL queries. Identifiers may be quoted with backticks; a reserved\nword used as a column name (e.g. `value`) must be quoted this way.\n\nLimitations:\n * Only a single read-only SELECT statement is allowed. INSERT, UPDATE, DELETE and any DDL are\n rejected. CTEs (WITH) and set operations (UNION, INTERSECT, EXCEPT) are allowed.\n * Window functions (the OVER clause) are not supported.\n * Only an allow-listed set of functions may be used; any other function is rejected:\n - Aggregates: COUNT, SUM, AVG, MIN, MAX, STDDEV, STDDEV_POP, STDDEV_SAMP, VARIANCE, VAR_POP,\n VAR_SAMP, BIT_AND, BIT_OR, BIT_XOR, ANY_VALUE, PERCENTILE_CONT, PERCENTILE_DISC.\n - Math: ABS, CEIL, CEILING, FLOOR, ROUND, TRUNCATE, MOD, POWER, SQRT, EXP, LN, LOG10, SIGN.\n - Date/time: EXTRACT, TIMESTAMPADD, TIMESTAMPDIFF, CURRENT_TIMESTAMP, CURRENT_DATE,\n CURRENT_TIME, LOCALTIMESTAMP, LOCALTIME, NOW.\n - Conditional / null handling: COALESCE, NULLIF, IFNULL.\n - String: LOWER, UPPER, TRIM, LENGTH, CHAR_LENGTH, CHARACTER_LENGTH, SUBSTRING, CONCAT,\n REPLACE.\n - JSON: JSON_VALUE, JSON_QUERY, JSON_EXISTS, JSON_TYPE, JSON_DEPTH, JSON_LENGTH,\n JSON_KEYS, JSON_PRETTY.\n - Type conversion: CAST.\n * Standard query clauses (WHERE, GROUP BY, HAVING, ORDER BY, LIMIT/OFFSET), JOINs, CASE\n expressions, IN, and comparison/boolean/arithmetic operators are always allowed.\n * A column holding JSON (e.g. `device_metadata_values.value_json`) is read with the JSON\n functions: JSON_VALUE(value_json, '$.value') extracts a scalar as a string, and\n JSON_QUERY(value_json, '$.tags') extracts a nested object or array. CAST the extracted\n value to compare or aggregate it as a number, filtering out the rows that do not hold\n one. A path that matches nothing gives NULL for JSON_VALUE and JSON_QUERY and FALSE for\n JSON_EXISTS, but is an error for JSON_LENGTH and JSON_KEYS unless it is prefixed with\n 'lax' (e.g. 'lax $.tags').\n * A query returns at most 100000 rows and must finish within 30 seconds.\n\nThe response uses a compact representation: `meta` lists the result columns in order (each entry\ncarries the column `name`), and `rows` holds one positional array of values per result row,\naligned by index with the columns in `meta`.\n\nPass `limit` and `offset` to read the result one page at a time; the page is applied inside the\nquery, so only those rows are produced. The response echoes `offset` and reports `hasMore`, which\ntells a pager whether another page follows.\n\nRequired permissions, when user-scoped authentication is used: `QUERY_DATA_ENGINE`.\n","operationId":"executeDataEngineQuery","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sql":{"type":"string","description":"A single read-only SQL SELECT statement to run against the organization data.","minLength":1,"maxLength":1024},"orgId":{"type":"integer","format":"int32","description":"Organization to run the query for. If not provided, the organization associated with the authentication token is used."},"limit":{"type":"integer","format":"int32","minimum":0,"maximum":100000,"default":0,"description":"Maximum number of rows to return. 0 (the default) returns as many rows as the 100000 row cap allows."},"offset":{"type":"integer","format":"int64","minimum":0,"maximum":2147483647,"default":0,"description":"Number of result rows to skip before the returned page starts."}},"required":["sql"]}}}},"responses":{"200":{"description":"Query executed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"array","description":"Result columns in order; each entry describes one column and is aligned by index with the values in every row array.","items":{"type":"object","properties":{"name":{"type":"string","description":"Column name."}}}},"rows":{"type":"array","description":"Result rows, each a positional array of column values aligned with meta.","items":{"type":"array","items":{}}},"offset":{"type":"integer","format":"int64","description":"Number of rows of the full result that precede the first returned row."},"hasMore":{"type":"boolean","description":"Whether the query had further rows beyond the returned ones — the next page, or the rows\nthe 100000 row cap cut off.\n"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"User is missing the QUERY_DATA_ENGINE permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Data Objects feature is disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.blynk.io/en/blynk.cloud/platform-https-api/data-objects.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.