Dynamically retrieve your data for a basic plugin & transform the result

Dynamically retrieve your data

The /query endpoint is called to request a particular slice of data from one dataset. All columns should be returned, in the same order as defined in the /datasets metadata for this set.

A set of filters is also sent along with the /query, but applying them to the data is fully optional for a basic plugin. After all, not every data store or API supports these operations. Applying the filters can reduce the number of rows to be sent, however, and thus positively impact the query performance. If you want to know how, you can read the academy article on applying filters.

In any case, Luzmo will still apply all filters (including eg. authorization filters that ensure customers cannot see particular data), as some filters might only be applicable after linking multiple sets which can potentially be sourced from different data sources or plugins.

A Luzmo request of the following format will be sent to your plugin:

POST /query

Content-Type: application/json
X-Secret: m2c0vilcn9q1qkeph06oycynp
X-Key: my_key
X-Token: my_token
X-Host: https://my.personal.example
{
  "id": "burrito_stats",
  "filters": [
    {
      "id": "date",
      "expression": "? > ?",
      "value": "2018-01-01"
    }
  ],
  "user": {
    "id": "098b9355-d043-46d5-be27-a511a04e46b7",
    "name": "Bill Murray",
    "email": "bill.murray@example.com"
  }
}

A basic plugin should always return all columns of the dataset in the same order as defined in the /datasets metadata for this set. Optionally, you are allowed to implement the filters. For more information on how to implement filters, please refer to the following article.

For the PostgreSQL example, you could based on the id in the above request construct the following SQL query:

SELECT *
FROM burrito_stats

Transform the result

If the database returns values which are different than what Luzmo expects, a transformation from database values to Luzmo values is necessary. Again, date types typically require the most attention, Luzmo expects them to be returned in the iso format, e.g. 2018-01-30T18:30:19.120Z.

To format values in the plugin, there are two options:

• format in the database: by including formatting functions in the query generation.
• format in the plugin: instead of returning the data straight from the database, we can run it through transformation code in the plugin. This GitHub code provides an example function (generateData) which implements a transformation that simply loops over the rows and parses the values before sending them back to Luzmo. Although we included the code here as an example, it is not used since the format of dates is already formatted by the database.