This is the ThingsDB documentation for version v0, click here for the latest version!

Example query

Query ThingsDB. A successful query request will respond with a DATA (18) package.


[scope, code, {vars}]

The vars in the query are optional and may be omitted. When used, vars must be a map where the keys represent the variable names and the values the values for the variable.

The socket needs to be authorized before sending a query request. See the auth example for how to authorize a socket connection.


As an example we will perform a useless query with as code just the simple equation 1 + 1; and we will use the @thingsdb scope to perform the query on.

This is the data we want to pack:

["@t", "1 + 1;"]

Serializing the above using MessagePack results in the following 11 bytes:

\x92\xa2@t\xa61 + 1;

Now we create the header. For this example we just use Id 0:

  • Data length (11) \x0b\x00\x00\x00
  • Identifier (0) \x00\x00
  • Query package type (34) \x22
  • Inverse type check bit (221) \xdd

Sending the Query package

\x0b\x00\x00\x00\x00\x00\x22\xdd\x92\xa2@t\xa61 + 1;

Responding Data package


We see that the DATA response package has a header with attached data of length 1.

Unpacking the data \x02 using MessagePack will return the expected value 2 which is the answer to our equation.

If your socket connection is not authenticated then you will receive an error response.