Quickstart

This guide helps you deploy XLTable and connect Excel to your analytical database as quickly as possible.

By the end of this guide you will have:

  • XLTable server running on Linux

  • A working database connection

  • A simple OLAP cube accessible from Excel Pivot Tables

For complete details on each step, see the full documentation sections.

Prerequisites

Before starting, make sure you have:

  • A Linux server (Ubuntu 22.04+ recommended) with sudo access

  • An analytical database (ClickHouse, BigQuery, Snowflake, Trino, StarRocks, Databricks, Greenplum or DuckDB)

  • Microsoft Excel (Microsoft 365 or Excel 2016+)

  • XLTable distribution file (contact help@xltable.com to obtain it)

Step 1: Install XLTable

Create the working directory:

sudo mkdir /usr/olap
sudo chmod a+rwx /usr/olap

Copy the distribution zip and the installer to the server:

scp xltable-*-ubuntu.zip install_ubuntu.zip user@your_server_ip:/usr/olap/

Unpack the installer scripts and run the install script:

cd /usr/olap
unzip -o install_ubuntu.zip
bash install_xltable.sh

The script will:

  • Install supervisor, nginx, unzip

  • Extract xltable to /usr/olap/xltable/

  • Create /usr/olap/xltable/setting/settings.json from the example (if missing)

  • Configure supervisor to autostart the service

  • Configure nginx as a reverse proxy on port 80

Step 2: Configure database connection

Open the settings file:

nano /usr/olap/xltable/setting/settings.json

Add your database connection and basic user credentials. Example for ClickHouse:

{
   "SERVER_DB": "ClickHouse",
   "CREDENTIAL_DB": {
      "user": "..",
      "password": "..",
      "host": "..",
      "port": "8443",
      "secure": true,
      "verify": true,
      "query_timeout": 300
   },
   "WRITE_LOG": false,
   "DUMP_XMLA": false,
   "LOG_RETENTION_DAYS": 14,
   "MAX_CELLS": 1000000,
   "OVERLOAD_GUARD": {
       "MAX_MEMORY_PERCENT": 90,
       "MAX_CPU_PERCENT": 95,
       "MIN_FREE_DISK_MB": 512
   },
   "CONVERT_FIELDS_TO_STRING": true,
   "USERS": {"user1": "pass1", "user2": "pass2"},
   "USER_GROUPS": {"user1": ["olap_users", "olap_admins"], "user2": ["olap_users"]},
   "ADMIN_GROUPS": ["olap_admins"],
   "CREDENTIAL_ACTIVE_DIRECTORY": {
      "server_address": "..",
      "domain": "..",
      "domain_full": "..",
      "username": "..",
      "password": "..",
      "access_groups": ["..", ".."]
   },
   "LDAP_CACHE_TIMEOUT": 300
}

Note

Changes to settings.json are picked up automatically within a few seconds of saving — no service restart is required.

For other database types, see Installation.

Step 3: Create a minimal OLAP cube

XLTable reads cube definitions from a table named olap_definition in your database.

For a ready-to-run example with sample tables, test data, and a complete cube definition, see ClickHouse Sample Data.

Step 4: Start the service

The install script starts the service automatically. To manage it manually:

Action

Command

Start

sudo supervisorctl start olap

Stop

sudo supervisorctl stop olap

Restart

sudo supervisorctl restart olap

Status

sudo supervisorctl status olap

Logs

sudo tail -f /var/log/supervisor/olap*.log

Step 5: Connect Excel

  1. Open Excel and go to Data → Get Data → From Database → From Analysis Services.

  2. Enter the server URL: http://your_server_ip

  3. Enter the username and password configured in settings.json.

  4. Select the myOLAPcube cube.

  5. Click Finish — your Pivot Table is ready.

Connection to XLTable is identical to connecting to Microsoft SQL Server Analysis Services (SSAS). For details on authentication modes and advanced connection options, see Connecting Excel.

Next steps

  • Installation — complete installation guide for Linux and Windows

  • OLAP cube definition — full OLAP cube definition reference

  • Reference — settings.json parameters and SQL tag reference

  • ClickHouse Sample Data — ready-to-run ClickHouse script with sample tables, test data, and the myOLAPcube cube

  • Support — troubleshooting and contact information