CSV & Excel Upload

Upload CSV and Excel files directly into Actyze for instant analysis. Files are imported into user-managed tables that can be queried immediately using natural language.

Overview

The file upload feature allows you to:

• Import CSV and Excel (.xlsx) files up to 50MB
• Create temporary tables (auto-deleted after 1-7 days)
• Create permanent tables for long-term storage
• Customize column data types
• Join uploaded data with existing databases

Supported File Formats

CSV Files

Requirements:

• UTF-8 encoding
• Header row required (must be first row)
• No empty header names
• Maximum 50MB file size

Example:

customer_id,customer_name,revenue,region
1,Acme Corp,150000,North
2,TechStart Inc,250000,West
3,Global Solutions,180000,East

Excel Files

Requirements:

• .xlsx format only
• Exactly ONE worksheet
• Header row must be first row
• No empty header names
• No merged cells
• Maximum 50MB file size

Why single worksheet? Multi-sheet Excel files are ambiguous - Actyze wouldn't know which sheet to import. Keep it simple with one sheet per file.

How to Upload

Step 1: Access File Upload

Navigate to Data Intelligence → File Imports in the Actyze interface.

Step 2: Select File

Click "Choose File" and select your CSV or Excel file. The system will automatically validate:

• File size
• File format
• Encoding (CSV only)
• Worksheet count (Excel only)
• Header requirements

Step 3: Configure Import

Table Name:

• Provide a descriptive name
• System automatically sanitizes and ensures uniqueness
• Example: customer_data becomes customer_data_abc123

Table Type:

• Temporary: Auto-deleted after retention period (default: 1 day)
• Permanent: Stored indefinitely

Retention Period (Temporary tables only):

• Minimum: 1 day
• Maximum: 7 days
• Default: 1 day

Step 4: Review Column Types

Actyze automatically detects column types:

• VARCHAR - Text data
• INTEGER - Whole numbers
• BIGINT - Large integers
• DOUBLE - Decimal numbers
• BOOLEAN - True/false values
• DATE - Date values
• TIMESTAMP - Date and time

Custom Types: You can override detected types if needed. For example, change a detected INTEGER to VARCHAR if the column contains codes that should be treated as text.

Step 5: Upload

Click "Upload" to create the table. The file is processed and immediately available for querying.

File Validation Rules

CSV Validation

Rule	Description	Example Error
Size	Must be ≤ 50MB	"File size (52.3MB) exceeds 50MB limit"
Encoding	Must be UTF-8	"File must be UTF-8 encoded"
Header	First row must be headers	"No header row found"
Column Names	No empty headers	"Found 2 empty header(s) at position(s): 3, 5"
Structure	Must have consistent columns	"Row 10 has different column count"

Excel Validation

Rule	Description	Example Error
Size	Must be ≤ 50MB	"File size (52.3MB) exceeds 50MB limit"
Worksheets	Exactly one worksheet	"Excel file must have exactly ONE worksheet. Found 3"
Header	First row must be headers	"Header row must be first"
Column Names	No empty headers	"Found empty header at column C"
Merged Cells	Not allowed	"Merged cells are not allowed. Found 3 merged cell(s)"
Formatting	No complex formatting	Data only, no formulas or macros

Querying Uploaded Data

Natural Language Queries

Once uploaded, query your data with natural language:

"Show me top 5 customers by revenue"
"What is the average revenue by region?"
"Find customers in the North region with revenue over 100000"

SQL Queries

Access uploaded tables through the user_uploads schema:

SELECT * FROM user_uploads.customer_data_abc123
WHERE region = 'North'
ORDER BY revenue DESC

Join with Existing Data

Combine uploaded data with existing databases:

SELECT 
  u.customer_name,
  u.revenue as uploaded_revenue,
  s.actual_revenue,
  s.actual_revenue - u.revenue as difference
FROM user_uploads.customer_data_abc123 u
JOIN production.sales s ON u.customer_id = s.customer_id

Managing Uploaded Files

View Your Tables

Navigate to Data Intelligence → File Imports to see all your uploaded tables:

• Table name
• Row count
• Created date
• Type (temporary/permanent)
• Expiration date (temporary tables only)

Delete Tables

Click the delete icon next to any table to remove it immediately.

Automatic Cleanup

Temporary tables are automatically deleted after their retention period expires. You'll receive a notification before deletion.

Use Cases

Ad-Hoc Analysis

Upload a CSV export from another system for quick analysis:

"Compare uploaded sales data with our CRM data"
"Show discrepancies between uploaded inventory and warehouse inventory"

Data Enrichment

Combine external data with internal databases:

"Join uploaded customer segments with transaction history"
"Merge uploaded product prices with sales performance"

Testing and Development

Use sample data for testing queries before running on production:

"Test query logic with uploaded sample dataset"
"Validate SQL generation with known test data"

Historical Snapshots

Create point-in-time snapshots for trend analysis:

"Compare Q1 uploaded metrics with Q2 uploaded metrics"
"Show month-over-month changes using uploaded snapshots"

Best Practices

File Preparation

Clean Data:

• Remove empty rows and columns
• Ensure consistent data types
• Fix encoding issues (convert to UTF-8)
• Remove special characters from headers

Optimize Size:

• Remove unnecessary columns
• Filter to relevant rows
• Compress large text fields
• Split very large files

Header Names:

• Use descriptive, clear names
• Avoid special characters
• Use underscores instead of spaces
• Keep names concise but meaningful

Table Management

Naming Convention:

customer_revenue_q1_2025
sales_snapshot_2025_02_07
inventory_import_weekly

Temporary vs Permanent:

• Use temporary for one-time analysis
• Use permanent for recurring reference data
• Set appropriate retention periods
• Clean up unused permanent tables

Performance

Large Files:

• Consider splitting files larger than 10MB
• Remove unnecessary columns before upload
• Use appropriate data types
• Index frequently queried columns (admin only)

Query Optimization:

• Filter uploaded data in queries
• Use specific columns instead of SELECT *
• Join on indexed columns when possible
• Limit result sets for large tables

Troubleshooting

Upload Fails

"File size exceeds 50MB"

• Split file into multiple smaller files
• Remove unnecessary columns
• Filter to relevant rows only

"Excel file must have exactly ONE worksheet"

• Delete extra worksheets
• Copy data to new workbook with single sheet
• Use CSV format instead

"UTF-8 encoding error"

• Open in text editor and save as UTF-8
• Use Excel: Save As → CSV UTF-8 (Comma delimited)
• Check for special characters

Validation Errors

"No header row found"

• Ensure first row contains column names
• Remove any title rows above headers
• Check for empty first row

"Empty header names"

• Fill in all column headers
• Remove empty columns
• Check for hidden characters

"Merged cells detected"

• Unmerge all cells in Excel
• Copy data and paste as values only
• Use CSV format to avoid formatting issues

Query Issues

"Table not found"

• Check table name in File Imports list
• Use user_uploads. schema prefix
• Verify table hasn't expired (temporary tables)

"Permission denied"

• Ensure you have USER or ADMIN role
• READONLY users cannot upload files
• Contact admin for role upgrade

Security & Privacy

Access Control

• Uploaded tables are visible only to the uploading user
• Admins can see all uploaded tables
• Tables cannot be shared between users (use permanent database tables for sharing)

Data Retention

• Temporary tables auto-delete after retention period
• Permanent tables remain until manually deleted
• No backup/recovery for deleted uploads
• Export important data before deletion

Data Storage

• Files stored in PostgreSQL database
• Data encrypted at rest
• Complies with organization security policies
• Subject to database backup policies

Permissions Required

Action	USER	ADMIN	READONLY
Upload files	✓	✓	✗
View own tables	✓	✓	✗
Query uploaded data	✓	✓	✓
Delete own tables	✓	✓	✗
View all user tables	✗	✓	✗
Delete any table	✗	✓	✗

Additional Resources

• RBAC Guide - Role-based access control
• Quick Start Guide - Query basics
• API Reference - Programmatic file upload

Support

For file upload issues:

1. Verify file meets all requirements
2. Check file size and encoding
3. Review validation error messages
4. Try CSV format if Excel fails
5. Contact support with error details