FAQ¶

What are the minimum system requirements for installing XLTable?¶

After installation, I see a message that no license is found or that xltable.lic is missing.¶

You need to upload a license file. Open the Admin Panel (see Admin panel).

Send the server ID to the vendor or partner who provided your distribution package. Then upload the license file you receive through the Admin Panel.

I cannot connect to the XLTable server from Excel.¶

I get errors such as “Connection failed, target computer actively refused it,” timeout errors, or an error on the first step of the connection wizard.

Check the connection guide: Connecting Excel
Run diagnostics: Support
In the Excel server field, always use the full URL with protocol: http://... or https://....
Also verify access to XLTable over ports 80/443.

Excel shows an XML parsing error, or curl returns HTTP 500 from the server.¶

Validate settings.json against the documented schema: settings.json schema.

Required blocks (including WRITE_LOG and CREDENTIAL_DB) must be present. Changes are picked up automatically within a few seconds of saving (a file with a JSON syntax error is ignored and logged, the previous configuration keeps working) — test the Excel connection again after saving (see Connecting Excel).

Can I store cube metadata in one ClickHouse instance and actual data in another?¶

Yes. Connections are defined in settings.json (CREDENTIAL_DB block), while cube definitions are stored in the olap_definition table.

More details:

XLTable cannot connect to ClickHouse databases.¶

Check CREDENTIAL_DB parameters (host, port, secure) using the examples in Database connections.

If ClickHouse accepts only TLS/HTTPS, install the correct certificate chain on the XLTable server and try again.

Where is the specific ClickHouse database configured?¶

The target database and connection parameters are configured in settings.json, in the CREDENTIAL_DB block:

If the olap_definition table does not exist, create it as shown in Cube definition storage.

How can I see SQL queries that XLTable sends to the database?¶

Set WRITE_LOG=true in settings.json (picked up automatically, no restart needed) and check XLTable logs:

You can also find the queries on the database side: every query is tagged with the app:xltable marker — see How can I view the query history of XLTable users in the database?.

How do I specify multiple users in settings.json?¶

Use this format:

"USERS": {
  "user1": "password1",
  "user2": "password2"
},
"USER_GROUPS": {
  "user1": ["group_name"],
  "user2": ["group_name"]
}

How can I view the query history of XLTable users in the database?¶

Every SQL query generated by XLTable carries a marker comment that identifies the application and the XLTable user who requested the data:

/* user:ivan.petrov, app:xltable */
SELECT ...

The comment is placed at the beginning of the query (for Snowflake — at the end, because Snowflake strips comments preceding the statement from its query history) and is preserved in the query history of every supported database, so you can always filter the history by app:xltable (and by user:<name> for a specific user). Below are ready-to-use queries per database.

ClickHouse — in addition to the comment, XLTable sets the same marker in the log_comment setting, which is stored as a separate column of system.query_log and allows exact filtering:

SELECT
    event_time,
    query,
    user,
    query_duration_ms
FROM system.query_log
WHERE log_comment LIKE 'user:%, app:xltable'
ORDER BY event_time DESC
LIMIT 10;

Greenplum — currently running queries are visible in pg_stat_activity:

SELECT pid, usename, query_start, state, query
FROM pg_stat_activity
WHERE query LIKE '/* user:%, app:xltable */%';

For a persistent history, enable statement logging on the server (log_statement = 'all' or log_min_duration_statement) and search the server log for app:xltable.

StarRocks — queries are recorded in the FE audit log (fe/log/fe.audit.log); search it for app:xltable. If the AuditLoader plugin is installed, the history is queryable with SQL:

SELECT `timestamp`, `user`, queryTime, stmt
FROM starrocks_audit_db__.starrocks_audit_tbl__
WHERE stmt LIKE '%app:xltable%'
ORDER BY `timestamp` DESC
LIMIT 10;

Trino — recent queries are kept in coordinator memory and shown in the Trino Web UI; with SQL:

SELECT created, user, state, query
FROM system.runtime.queries
WHERE query LIKE '%app:xltable%'
ORDER BY created DESC
LIMIT 10;

Snowflake — up to 365 days via ACCOUNT_USAGE (shows queries of all users; requires access to the SNOWFLAKE database, e.g. the ACCOUNTADMIN role; new queries appear with up to ~45 minutes of latency):

SELECT start_time, user_name, total_elapsed_time, query_text
FROM snowflake.account_usage.query_history
WHERE query_text LIKE '%app:xltable%'
ORDER BY start_time DESC
LIMIT 10;

Databricks — via the Query History page of the workspace UI, or with SQL if system tables are enabled:

SELECT start_time, executed_by, total_duration_ms, statement_text
FROM system.query.history
WHERE statement_text LIKE '%app:xltable%'
ORDER BY start_time DESC
LIMIT 10;

BigQuery — via INFORMATION_SCHEMA.JOBS of the region your datasets live in (replace region-eu with your region):

SELECT creation_time, user_email, total_bytes_processed, query
FROM `region-eu`.INFORMATION_SCHEMA.JOBS
WHERE query LIKE '%app:xltable%'
ORDER BY creation_time DESC
LIMIT 10;

DuckDB — the embedded database has no server-side query history; use WRITE_LOG=true in settings.json to see the queries in XLTable logs instead.

Data in storage updates frequently; we need to refresh cache. Is configurable cache TTL planned?¶

The cache TTL is configurable: the METADATA_CACHE_TTL setting (600 seconds by default) limits how long cube metadata and query results are served from the cache before being re-read from the database, and SQL_CACHE_TTL (default: the METADATA_CACHE_TTL value) limits how long SQL query results are shared between users. See Caching and settings.json schema.

To refresh immediately, use the standard methods:

Refresh in Excel (Refresh / Refresh All)
Clear Metadata Cache in the Admin Panel
POST /api/cache/clear from your ETL pipeline — clear the cache automatically right after the warehouse data is updated, so users get fresh data without waiting out the TTL (see Cache management API)

Documentation:

Why are cube changes not visible to users after updating the cube?¶

An edited cube definition is picked up automatically within METADATA_CACHE_TTL (600 seconds by default). To apply it immediately, use Clear Metadata Cache in the Admin Panel (http://<server>/admin) — users stay signed in — or click Refresh in Excel for an individual user.

Excel queries run too long or timeout; a ClickHouse view is slow while a physical table is faster.¶

Enable logging first and verify the actual SQL query. To improve performance, reduce the number of fields/dimensions in the model and PivotTable. For heavy sources, use narrower views or materialized tables in ClickHouse.

Why is the number of rows returned by XLTable higher than in another analytics system with a similar report layout?¶

Row counts may differ due to different result granularity. XLTable can include intermediate totals, not only leaf-level rows. Compare systems with identical dimensions, filters, and subtotal settings.

See SQL generation logic.

How does XLTable generate SQL from a cube definition: are all CTEs executed or only the required ones?¶

XLTable generates a query based on the current context of the fields selected in Excel. Only the required tables and fields are used, not the entire model.

For CTEs, only the parts actually used in the query participate in execution.

Useful documentation sections:

The XLTable service does not start automatically after server reboot.¶

Check the service management instructions: Service Management.

On Linux, the default setup is often supervisor. Check:

status: sudo supervisorctl status 'olap:*'
logs: sudo tail -f /var/log/supervisor/olap*.log
execute permissions for the binary file

What access is usually required for a contractor to configure a cube?¶

Typical access includes:

SSH/admin access to the XLTable server
XLTable access to ClickHouse
permissions on olap_definition for cube upload/update
network access for Excel users to XLTable over 80/443 (or via VPN)

Step-by-step docs:

The client is migrating from Microsoft SQL Server and SSAS. Can we avoid creating extra objects in ClickHouse?¶

Yes. You can reduce the number of intermediate ClickHouse objects by moving part of the logic into the XLTable cube definition (SQL + tags).

References:

SSAS comparison: Comparison with SSAS
Cube definition rules: OLAP cube definition

We need to combine two attributes from different tables into one dimension, but an error occurs.¶

For attributes from different tables, create separate dimensions and join sources using LEFT JOIN in the cube definition.

Working example: Unified example.

ClickHouse does not allow nesting window functions inside aggregates like MDX in Microsoft tools. How can we replicate multi-step measure logic?¶

Use Jinja scripts in the cube definition for multi-step measure logic. This allows you to inject filters and transform SQL before execution.

Documentation:

What is the license cost and trial period length?¶

Pricing information is available at: https://xltable.com/#pricing

How are licensed users counted?¶

XLTable licenses are per named user, not per concurrent connection. A licensed seat is assigned to a user on their first request and stays assigned to that user — signing out, closing Excel or clearing the server cache does not free the seat. A seat is released:

automatically, after a period of user inactivity defined by the license (30 days by default) — so seats of employees who left are recycled without administrator involvement;
manually, by an administrator on the License tab of the admin panel (the Release button, which also signs that user out).

When all seats are taken, a new user receives a clear “Named user limit reached” message in Excel; existing users are unaffected. The admin panel shows who occupies the seats and when each user was last active. To add seats, contact the vendor for an updated license file.

Is a trial installation on Microsoft Windows available? Why would a Windows server be needed?¶

Yes, a Windows Server distribution is available on request.

Installation instructions: Windows Server (IIS).

For pilots, Linux deployment is usually simpler. Windows is typically chosen when IT policy requires IIS and Microsoft domain integration.

Can XLTable be connected from LibreOffice or OpenOffice?¶

Currently, the service works only with Excel. Support for other clients is planned for the future.

Excel cannot connect to the server.¶

Verify the server address is reachable from the client machine (port 80 or 443).
Check that Nginx is running: sudo service nginx status.
Check that XLTable is running: sudo supervisorctl status.

I get an authentication error in Excel.¶

Verify the username and password in settings.json under the USERS key.
If using Active Directory, verify the CREDENTIAL_ACTIVE_DIRECTORY settings.
Changes to settings.json are picked up automatically within a few seconds of saving.

The Pivot Table shows no data.¶

Confirm the olap_definition table exists in the database and contains at least one cube definition.
Enable logging and check the generated SQL queries for errors.
Verify the database credentials in CREDENTIAL_DB have read access to the relevant tables.

Queries are slow.¶

Enable WRITE_LOG to inspect the generated SQL and identify bottlenecks.
Pre-aggregate data in the database where possible.
Reduce the number of dimensions selected in the Pivot Table.

The Pivot Table reports “too many data cells”.¶

The result size limit is measured in cells of the pivoted table (rows × columns × measures), 100,000 by default. Adjust MAX_CELLS in settings.json if needed (the legacy MAX_ROWS key is still accepted).
Add filters in the Pivot Table to reduce the result set.
A separate message appears when the columns area produces more than 16,384 columns (the Excel sheet limit) — move fields from columns to rows or apply filters.

The XLTable service does not start on Linux.¶

Check the service status and the Supervisor logs:

sudo supervisorctl status 'olap:*'
sudo tail -f /var/log/supervisor/olap*.log

The XLTable service does not start on Windows.¶

XLTable on Windows runs under IIS (FastCGI):

Check that the IIS application pool is started (IIS Manager → Application Pools).
Verify the FastCGI application is registered with the correct paths to python.exe and wfastcgi.py (see Windows Server (IIS)).
Check the Windows Event Log and the XLTable log folder for error output.