Querybook #

Querybook is a browser-based data analysis tool that turns SQL queries into natural language reports and graphs called DataDocs. After you clone and build the Querybook GitHub project, it runs as a Docker application. You can connect to Starburst Galaxy, Starburst Enterprise platform (SEP), and Trino clusters.

Client requirements #

To run Querybook and connect it to clusters, you must have:

• Git
• Docker Desktop installed and known working, with at least 5 GB of RAM dedicated to it.
• Internet access for the Docker build process.
• Configuration settings in your Querybook directory.

Querybook is a Python-based web application that runs in your browser, but it is delivered as a Docker application that you build and run locally. As the Docker application assembles, it pulls Python 3.6+ and the Python trino package into the Docker container image. This explains why Querybook does not need either Python or the trino package to be installed locally.

Install and run Querybook #

There are three steps to install and run Querybook.

1. Clone Querybook’s GitHub repository:

   cd <work-directory>
   git clone git@github.com:pinterest/querybook.git
   

2. Go into the cloned directory and run make.

   cd querybook
   make
   

   The Docker image assembly process can take several minutes.

3. When the Docker build finishes, it leaves a web server running locally. Open a browser on https://localhost:10001.

Querybook can run without configuration, which allows you to create a local login name and password and run the built-in demo.

Configure Querybook #

Querybook configuration can be complex. The web documentation is also delivered in Markdown format in docs_website/docs.

You can make configuration changes with the Admin UI at https://localhost:10001/admin or by directly editing configuration files, then re-running make.

In general, you must:

• Configure the components to assemble into the Docker container.
• Configure the URL and authentication to access your cluster.

The following shows one possible configuration of container components, specified in a file named local.txt in the requirements folder. Querybook has built-in support for the Trino search engine, so it only needs to be invoked by name from the engine folder.

# Engines
-r engine/trino.txt

# Metastores
-r metastore/hms.txt
-r metastore/glue.txt

# Auth
-r auth/oauth.txt
-r auth/ldap.txt

# Result Store
-r platform/aws.txt