Static Tables from CSV

Upload CSV files to create queryable tables in Cluvio without connecting to a database. This is useful for analyzing smaller or rarely changing datasets such as spreadsheet exports, third-party data exports, or reference data.

Requirements

• Encoding: CSV files must use UTF-8.
• File size: A single file can be at most 250 MiB in size. Larger files must be split.
• Continuity: Only lines at the beginning of the file can be skipped. All following lines must be CSV data, with the exception of a single optional header line for the column names.
• Column separator: Comma, semicolon or tab is supported as a column separator.
• Column consistency: All rows must have the same number of columns for the chosen separator.

Creating Static Tables

Step 1: Upload CSV

To create a static table from a CSV file:

1. Select Add Static Table on the datasources overview page.
2. Click Select File and choose your CSV file.
3. The file uploads securely to Cluvio's servers.
4. Cluvio analyzes the file and detects CSV parsing configuration.

After successful upload and analysis, proceed to configure how your data will be represented as a table.

Step 2: Configure Data

1. Verify CSV parse settings

Review the detected settings at the top of the dialog and adjust if needed:

• Column separator (comma, semicolon, tab, etc.)
• Decimal separator (dot or comma)
• With header row (yes/no)
• Skip lines (number of initial lines to skip)

2. Review and customize columns

Use the Column List to see all detected columns and exclude any you don't need.

For each column, the Column Detail view provides:

• Value distribution histograms and frequency analysis.
• Detection of empty values, uniqueness, min/max values.
• Invalid value reporting with specific line numbers.

Customize each column as needed:

• Rename columns for clarity in your SQL queries.
• Change column types if auto-detection needs adjustment.
• Customize date/time formats.
• Configure how invalid values should be handled (skip value, skip row, or error).

3. Preview the data

Select Preview Table to view the first 100 rows of parsed data. Verify that the columns show the expected values. If the values for a column look incorrect, return to the column detail to adjust the column configuration as necessary. If everything looks correct, proceed to the final step.

Step 3: Table Name and Time Zone

Configure final table settings:

• Table Name: Must be unique across all static tables. This is the name you will use in your SQL queries.
• Source File Time Zone: Static tables store all date/time values in UTC. If the values in your file do not represent UTC, choose the appropriate time zone from the drop-down. For example, if your file contains the value 2025-01-15 14:30 and you select America/New_York, Cluvio interprets this value as 2:30 PM Eastern Time and it is converted to UTC accordingly. When querying your static table, you will always see date/time values in UTC unless a dashboard time zone is in effect.

Using Your Static Table

After creating a static table, you can query it using the Static Tables datasource:

-- Simple query
SELECT * FROM my_sales_data
WHERE order_date >= '2025-01-01'
ORDER BY order_date DESC
LIMIT 100;

-- Aggregation
SELECT
  product_category,
  COUNT(*) as order_count,
  SUM(total_amount) as total_revenue
FROM my_sales_data
WHERE order_date >= '2025-01-01'
GROUP BY product_category
ORDER BY total_revenue DESC;

-- Join multiple static tables
SELECT
  orders.order_id,
  orders.order_date,
  products.product_name,
  products.category
FROM order_export AS orders
JOIN product_list AS products
  ON orders.product_id = products.id
WHERE orders.order_date >= '2025-01-01';

The table name you set in Step 3 becomes the table name in your SQL queries.

Reconfiguring a Static Table

You can change how the CSV file is represented as a static table without re-uploading the file. This is possible because Cluvio retains the original file. When you change the configuration, the file is simply re-processed. Thus, you can adjust column types, names, formats, which columns are excluded and other parse settings any time after the initial upload. Just be mindful of existing reports or filters using this static table.

To download the original file, select the Download action on the Configuration tab.

Uploading Updated Data

To update a static table with new data, use the Replace function to upload a new CSV file. The new file is analyzed with the existing configuration. New columns are automatically included. You can review and adjust all parse settings.

Value Types and Formats

Cluvio supports the following value types for CSV data:

Type	Description	Example Values	Formats & Limits
Boolean	True or false values	true, false	Case-insensitive
Integer	Whole numbers	42, -1000, 0	Signed 64-bit (-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807)
Float	Decimal numbers	3.14, -0.5, 1.23e10	64-bit floating-point (double precision)
String	Text values	Hello, Product A	UTF-8 encoded, max 1 MiB (1,048,576 bytes) per value
Date	Calendar dates	2025-12-14 12/24/2025 24.12.2025	Pre-defined: ISO 8601, US, EU Custom: See Date-Time Formats
Time	Time of day	15:10:30 12:00 AM	Pre-defined: ISO 8601, AM/PM Custom: See Date-Time Formats
DateTime	Date and time combined	2025-12-14T14:15:30 2025-12-14 14:15:30	Pre-defined: ISO 8601, RFC 3339, UNIX timestamp Custom: See Date-Time Formats

Custom Date and Time Formats

For Date, Time, and DateTime columns, you can define custom formats using format specifiers:

Date specifiers: YYYY, MMMM, MMM, MM, M, DD, D Time specifiers: HH, H, hh, h, mm, ss, A, a Allowed separators: whitespace, ,, -, :, ., /, T, |

See the Date-Time Formats guide for complete details on custom formats.

Best Practices

File Preparation

• Include a header row: Having column names in the first row helps Cluvio detect your data structure. You can customize or add column names during the CSV configuration step.
• Clean your data: Remove footer rows and summary sections before uploading. If your file has metadata or extra headers at the top, you can skip a certain number of rows during the CSV configuration step, but any intermittent lines not representing actual data must be removed.
• Consistent formatting: Ensure date and number formats are consistent throughout each column.
• Column names: Simpler names make querying easier (e.g., order_date, total_amount rather than Order Date (USD)). You can customize column names during the CSV configuration step.
• File size: Split files larger than 250 MB into smaller files or aggregate data before uploading.
• Encoding: Save files as UTF-8 to avoid character encoding issues.

Data Type Configuration

• Review auto-detection: Always check the automatically detected column types in Step 2.
• Date formats: Verify date/time formats match your data. Use the preview to confirm parsing is correct.
• Timezone setting: Set the file data timezone to match the timezone of your source data.
• Exclude unused columns: Remove columns you don't need to reduce data size and improve query performance.

Query Performance

• Filter early: Use WHERE clauses to filter data before aggregations.
• Limit row scanning: Use LIMIT when testing queries or exploring data.
• Index alternatives: Since static tables don't support indexes, keep tables focused and avoid unnecessary columns.
• Join carefully: When joining multiple static tables, filter each table before joining when possible.

Maintenance

• Regular updates: When data changes, use the Replace function to upload updated files.
• Monitor data size: Check your total static table data size against your plan limits.
• Document sources: Use clear table names that indicate the data source and update frequency (e.g., sales_export_2025_q1).
• Test after updates: After replacing a table, verify that existing reports and dashboards still work correctly.