Overview
Column metadata configuration allows you to provide business context for your data columns, significantly improving the Query Builder’s ability to understand and answer questions about your data.Auto-Detection
Automatic data type and format detection on import
Business Context
Add descriptions and categories for better AI understanding
AI Suggestions
Get AI-powered description suggestions
Templates
Apply pre-configured metadata from templates
Why Configure Column Metadata?
When you import a CSV file, the Query Builder automatically detects column names and basic data types. However, it doesn’t know the business meaning of your data.The Problem
Consider a column namedInspector_Detail_Date_stop_date. Without context, the AI might not understand:
- What this date represents
- How it relates to other columns
- What valid date ranges are expected
The Solution
By adding metadata, you help the AI understand:- This is a date field representing when a condition report was completed
- Valid values range from January 2024 to present
- It relates to the
start_datecolumn (same inspection session) - It belongs to the “CR Data” category
Well-configured column metadata can dramatically improve query accuracy, reducing the need for query refinement.
Auto-Detected Metadata
When you import a dataset, the system automatically analyzes each column and detects:| Detection | Description | Example |
|---|---|---|
| Data Type | String, number, date, boolean, timestamp | date |
| Date Format | Supported date patterns | YYYY-MM-DD |
| Date Range | Min/max dates in the column | 2024-01-01 to 2024-12-31 |
| Numeric Range | Min/max values for numbers | 0 to 1000 |
| Categorical | Columns with limited unique values | ≤50 unique values |
| Sample Values | Representative values from the data | "Lease", "Consignment" |
| Primary Identifier | Columns likely to be identifiers | vin, stock_number |
Data Type Detection
The system infers data types by analyzing actual values:| Type | Detection Logic |
|---|---|
| date | Values match common date patterns (YYYY-MM-DD, MM/DD/YYYY, etc.) |
| timestamp | Date patterns with time component |
| number | All non-null values are numeric |
| boolean | Values are true/false, yes/no, 1/0 |
| string | Default for unrecognized patterns |
Categorical Detection
A column is marked as categorical when:- It has a limited number of unique values (≤50 by default)
- Sample values are captured for query suggestions
- The AI uses these values for accurate filtering
Configuring Column Metadata
Accessing the Editor
Editable Fields
For each column, you can configure:| Field | Purpose | Example |
|---|---|---|
| Display Name | Human-readable name shown in UI | ”Check-In Date” |
| Description | Business context for the AI | ”Date the vehicle was received at the auction” |
| Category | Group columns by domain | ”Check-In Data”, “CR Data”, “Vehicle Info” |
Column Editor Features
Inline Editing
Inline Editing
Click on any field to edit it directly in the table. Changes are saved automatically.
- Click display name → Edit name
- Click description → Edit description
- Click category dropdown → Select or create category
AI-Powered Suggestions
AI-Powered Suggestions
Click the Suggest button next to any column to have AI generate a description based on:
- Column name analysis
- Sample data values
- Data type and format
- Common patterns in automotive data
Bulk Category Assignment
Bulk Category Assignment
Select multiple columns and assign them to a category at once:
- Check the boxes for columns to update
- Click Bulk Actions → Assign Category
- Select or create a category
- Click Apply
JSON Import/Export
JSON Import/Export
Export and import metadata as JSON for:
- Backing up configurations
- Sharing metadata between environments
- Version controlling metadata changes
Copy from Another Dataset
Copy from Another Dataset
If you have a similar dataset already configured:
- Click Copy from Dataset
- Select the source dataset
- Matching columns are automatically configured
- Review and adjust as needed
Category Organization
Categories group related columns together, making it easier for:- Users to navigate large datasets
- AI to understand column relationships
- UI to display organized column lists
Recommended Categories
| Category | Use For |
|---|---|
| Vehicle Identification | VIN, stock number, run number |
| Check-In Data | Arrival dates, check-in user, receiving info |
| CR Data | Condition report dates, writer, completion info |
| Sale Data | Sale type, seller, buyer, auction lane |
| Location | Physical location, lot, bay information |
| Timestamps | Created/updated timestamps, processing times |
| Calculated | Derived fields and computations |
Creating Custom Categories
Best Practices
Writing Effective Descriptions
Do
- Be specific about business meaning
- Include valid value ranges
- Note relationships to other columns
- Mention data quality considerations
Don't
- Use technical jargon only
- Leave descriptions empty
- Duplicate the column name
- Include sensitive information
Description Examples
| Column | Poor Description | Good Description |
|---|---|---|
check_in_date | ”A date" | "Date vehicle arrived at auction. Used to calculate days-on-lot and time-to-CR metrics.” |
sale_type | ”Type" | "Vehicle sale category: ‘Lease’ (off-lease returns) or ‘Consignment’ (dealer/fleet consignments). Affects processing requirements.” |
cr_writer_id | ”Writer ID" | "User ID of the condition report writer. References users table. Used for writer productivity analysis.” |
Maintaining Metadata Quality
- Review Auto-Detected Values: Verify the system correctly identified data types
- Add Context After Import: Configure descriptions before heavy Query Builder use
- Update When Schema Changes: Re-verify metadata after CSV format changes
- Use Templates: Apply templates for consistent metadata across similar datasets
Viewing Metadata Impact
In Query Builder
Configured metadata appears in the Query Builder’s column reference panel:- Display names replace raw column names
- Descriptions appear in tooltips
- Categories group columns in the panel
- Sample values inform filter suggestions
In Smart Suggestions
The Query Builder uses metadata to generate contextual suggestions:- Time-based queries for date columns
- Categorical breakdowns for enum columns
- Aggregations for numeric columns
- Comparisons using related columns
Troubleshooting
Column not showing correct type
Column not showing correct type
Cause: Auto-detection may misidentify types for mixed dataSolution:
- Open Column Metadata Editor
- Find the column
- Manually set the correct data type
- Re-trigger analysis if needed
AI suggestions seem generic
AI suggestions seem generic
Cause: Column name doesn’t provide enough contextSolution:
- Add a descriptive display name
- Provide sample context in description
- Re-request AI suggestion
Categories not appearing in Query Builder
Categories not appearing in Query Builder
Cause: Category assignment not savedSolution:
- Check that changes were saved (look for confirmation)
- Refresh the Query Builder page
- Ensure dataset is selected in the selector