Turnilo is a business intelligence, data exploration, and visualization web application specifically designed for Apache Druid.

It is a fork of Pivot (which is under commercial license) and was originally forked from the Swiv repository. Turnilo's primary goal is to provide a simple yet powerful user interface for non-technical users to interact with Druid datasets.

The refreshRule: section defines how Turnilo discovers the latest available data in a source. Use the appropriate rule type based on your data source characteristics:

• query (default): Best for batch data. Turnilo queries the source every minute to find the maximum value in the time dimension.
• realtime: Best for realtime data. Turnilo assumes the value of now is the latest data time without querying.
• fixed: Best for constant data. Turnilo uses the specific timestamp provided in the time property.

If using the fixed rule, you must provide a time property as an ISO 8601 Instant.

refreshRule:
  rule: fixed
  time: "2023-10-27T10:00:00Z"

Turnilo provides three primary extension points depending on your goal:

1. Request decorator: Modify all Druid queries sent to the Druid cluster (at the cluster configuration level).
2. Query decorator: Modify all Plywood queries sent to Druid (at the data cube configuration level).
3. Plugins: Extend the entire backend application (at the top-level configuration level).

Use the turniloMetadata object on the Request to pass values between plugins and decorators without polluting HTTP headers.

Turnilo is optimized for low-latency Apache Druid interactions and provides the following capabilities:

• Drag-and-drop UI: An intuitive interface for visualizing Druid datasets.
• Druid Query Support: Fully dedicated support for Druid-specific query types, including:
  • Timeseries queries
  • TopN queries
  • GroupBy queries
• Unified Data View: A single view for both historical and real-time data.
• Performance: Designed to be fast and responsive for interactive data exploration.

Turnilo attaches a turniloMetadata object to every Request. This is a namespace for storing values that need to persist with a request.

A special property loggerContext is a Record of values that the logger will automatically include in every log message. This is useful for attaching context like User Agents or User IDs to all logs generated during a request lifecycle.

app.use(function(req, res, next) {
  req.turniloMetadata.loggerContext.userAgent = req.get('User-Agent');
  next();
});

Turnilo provides two ways to silently apply filters to all queries made to a data cube for row-level security:

1. subsetFormula: Define a boolean Plywood filter clause in the data source configuration. This formula is automatically applied to every query.
2. queryDecorator: Define a function that decorates the Plywood query. This function is called for every query and has access to the Request object, allowing for dynamic filtering based on request context.

# Example using subsetFormula for row-level security
# This ensures users only see data where country is 'United States'
subsetFormula: '$country == "United States"'

Data cubes are defined under the top-level dataCubes: key in the configuration. The order in which you list them in the config determines their display order in the Turnilo UI. Each data cube represents a set of data (typically from Druid) that users can explore.

dataCubes:
  - name: my_first_cube
    title: My First Data Cube
    # ... other properties

To contribute to or build Turnilo from source, ensure you have Node.js 14.x or 16.x installed.

Important: Use npm for dependency management and builds; do not use yarn.

Setup and Build

1. Install dependencies: npm install
2. Build the project: npm run build

Running the project

Standard Mode

• Run examples: npm run start:examples
• Connect to Druid: npm run start -- connect-druid http[s]://druid-broker-hostname[:port]
• Use a config file: npm run start -- run-config path/to/config.yml

Developer Mode (with Hot Reloading)

In developer mode, frontend changes trigger automatic recompilation and page reloads.

• Run examples: npm run start:dev:examples
• Connect to Druid: npm run start:dev -- connect-druid http[s]://druid-broker-hostname[:port]
• Use a config file: npm run start:dev -- run-config path/to/config.yml

You can control which data cubes are visible and queryable in Turnilo using two primary methods:

1. Explicit Definition: Disable source discovery in the configuration and explicitly define only the data cubes you want users to see. Any cube not explicitly defined will be inaccessible.

2. Auth Proxy Header: Use an authentication proxy (like Nginx) to inject the x-turnilo-allow-datacubes header into requests. This header should contain a comma-delimited list of allowed data cube names. Use * as a wildcard for all cubes.

To enforce these restrictions, you must enable the guardDataCubes flag in the clusters section of your configuration.

# Enable the guard to enforce data cube restrictions
clusters:
  - name: druid
    guardDataCubes: true

Example x-turnilo-allow-datacubes header values:

"*"

"some-name"

"name1,name2"

"name1,name2,*"

To quickly see Turnilo in action, you can run it with pre-configured example datasets. Once running, access the interface at http://localhost:9090/.

turnilo run-examples