Run a VoidQL query

Runs one read-only VoidQL SELECT over the project and returns up to limit rows (100 by default, at most 10,000) with isTruncated when there were more.

getSchema lists the tables and their columns. Running a query changes nothing, so it is safe to repeat. Personal data (people's email, name and traits, and event keys that identify a person, such as properties.$email or context.$ip) needs the project:persons:read permission as well. A query runs for at most 20 seconds.

Guide: Query analytics with VoidQL

Authorization

AuthorizationBearer <token>

A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.

In: header

Path parameters

projectId*string

The project's id, proj_.... A secret key works only in the project it belongs to.

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

query*string

The VoidQL SELECT to run, up to 50,000 characters.

Length1 <= length <= 50000

limit?|

The most rows to return, from 1 to 10,000; 100 when omitted.

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/analytics/voidql/query" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "query": "SELECT store, count() AS active FROM subscriptions WHERE is_active GROUP BY store",    "limit": 100  }'

{  "columns": [    {      "name": "store",      "type": "String"    },    {      "name": "active",      "type": "UInt64"    }  ],  "rows": [    {      "store": "apple-app-store",      "active": 1840    },    {      "store": "stripe",      "active": 312    }  ],  "isTruncated": false}

{  "error": {    "type": "invalid_request",    "code": "voidql_syntax",    "message": "line 1, col 8: Unexpected keyword 'FROM'.",    "param": "query"  }}

{  "error": {    "type": "unauthenticated",    "code": "invalid_api_key",    "message": "This secret key is not valid."  }}

{  "error": {    "type": "permission_denied",    "code": "personal_data",    "message": "line 1, col 8: Column 'email' of persons is personal data, so the whole query was rejected: reading it needs the project:persons:read permission in every project the query covers. Leave it out (people.id identifies a person without it), or ask someone with that permission."  }}

{  "error": {    "type": "not_found",    "code": "project_not_found",    "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.",    "param": "projectId"  }}

{  "error": {    "type": "rate_limited",    "code": "voidql_quota",    "message": "Too many queries for this organization right now. Try again in a minute."  }}

{  "error": {    "type": "internal",    "code": "internal_error",    "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing."  }}

{  "error": {    "type": "unavailable",    "code": "voidql_timeout",    "message": "The query took longer than 20 seconds. Narrow its time range or projects, or aggregate more."  }}

Response body

`application/json`

Errors

Status	`type`	`code`	When
400	`invalid_request`	`voidql_syntax`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_unsupported`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_unknown_relation`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_unknown_field`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_too_complex`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_rejected`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
403	`permission_denied`	`personal_data`	For personal data without the permission.
429	`rate_limited`	`voidql_quota`	When the organization runs too many queries.
503	`unavailable`	`voidql_timeout`	When the query could not finish.
503	`unavailable`	`voidql_memory`	When the query could not finish.
503	`unavailable`	`voidql_unavailable`	When the query could not finish.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

Authorization

AuthorizationBearer <token>

A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.

In: header

Path parameters

projectId*string

The project's id, proj_.... A secret key works only in the project it belongs to.

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

query*string

The VoidQL SELECT to run, up to 50,000 characters.

Length1 <= length <= 50000

limit?|

The most rows to return, from 1 to 10,000; 100 when omitted.

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/analytics/voidql/query" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "query": "SELECT store, count() AS active FROM subscriptions WHERE is_active GROUP BY store",    "limit": 100  }'

{  "columns": [    {      "name": "store",      "type": "String"    },    {      "name": "active",      "type": "UInt64"    }  ],  "rows": [    {      "store": "apple-app-store",      "active": 1840    },    {      "store": "stripe",      "active": 312    }  ],  "isTruncated": false}

{  "error": {    "type": "invalid_request",    "code": "voidql_syntax",    "message": "line 1, col 8: Unexpected keyword 'FROM'.",    "param": "query"  }}

{  "error": {    "type": "unauthenticated",    "code": "invalid_api_key",    "message": "This secret key is not valid."  }}

{  "error": {    "type": "permission_denied",    "code": "personal_data",    "message": "line 1, col 8: Column 'email' of persons is personal data, so the whole query was rejected: reading it needs the project:persons:read permission in every project the query covers. Leave it out (people.id identifies a person without it), or ask someone with that permission."  }}

{  "error": {    "type": "not_found",    "code": "project_not_found",    "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.",    "param": "projectId"  }}

{  "error": {    "type": "rate_limited",    "code": "voidql_quota",    "message": "Too many queries for this organization right now. Try again in a minute."  }}

{  "error": {    "type": "internal",    "code": "internal_error",    "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing."  }}

{  "error": {    "type": "unavailable",    "code": "voidql_timeout",    "message": "The query took longer than 20 seconds. Narrow its time range or projects, or aggregate more."  }}

Response body

`application/json`

Errors

Status	`type`	`code`	When
400	`invalid_request`	`voidql_syntax`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_unsupported`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_unknown_relation`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_unknown_field`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_too_complex`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
400	`invalid_request`	`voidql_rejected`	With a message saying what to change, where `param` names the field of an unknown one and a rejection names the database's error code.
403	`permission_denied`	`personal_data`	For personal data without the permission.
429	`rate_limited`	`voidql_quota`	When the organization runs too many queries.
503	`unavailable`	`voidql_timeout`	When the query could not finish.
503	`unavailable`	`voidql_memory`	When the query could not finish.
503	`unavailable`	`voidql_unavailable`	When the query could not finish.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

Authorization

Path parameters

Request body

Examples

Response body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Errors

More in VoidQL

Run a VoidQL query

Authorization

Path parameters

Request body

Examples

Response body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Errors

More in VoidQL

Run a VoidQL query

voidql_syntax

voidql_unsupported

voidql_unknown_relation

voidql_unknown_field

voidql_too_complex

voidql_rejected

voidql_timeout

voidql_memory

voidql_unavailable

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

Run a VoidQL query

voidql_syntax

voidql_unsupported

voidql_unknown_relation

voidql_unknown_field

voidql_too_complex

voidql_rejected

voidql_timeout

voidql_memory

voidql_unavailable

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`