FAQ

Frequently asked questions about Shadowfax, organized by topic.

---

Getting Started

What is Shadowfax?

Shadowfax is an AI-powered analytics platform where non-technical users can perform sophisticated data analysis through natural language conversations. The AI agent automatically creates SQL Views, builds analytical pipelines, and generates visualizations—all from simple prompts.

You don't write code. You just talk to your data.

Do I need to know SQL or coding?

No. You don't need to write any SQL. The AI agent writes it for you.

However, you will see SQL in the interface. Each View (transformation) shows you the SQL code it used. This transparency helps you:

• Verify the logic is correct
• Learn SQL patterns over time
• Debug if something looks wrong
• Edit directly if you want to (optional)

Think of it like having a SQL expert on your team who does all the coding for you.

What's a Workbook?

A Workbook is your analytical workspace for a project. It's like a database that holds:

• Sources: Your original data (CSV uploads)
• Views: SQL transformations the AI creates
• AI Tables: Views with AI-generated columns
• Visualizations: Charts and dashboards
• Answers: Saved results from Quick Answers

Everything for one analysis project lives in one Workbook.

Coming soon: Live database connections will allow you to connect to Snowflake, BigQuery, Databricks, Clickhouse, and Redshift.

What's the difference between Sources, Views, and AI Tables?

Concept	What It Is	Example
Sources	Your original, immutable data. Lives in sources schema.	sources.orders, sources.customers
Views	SQL transformations created by the AI. Reusable, reactive. Lives in main schema.	main.monthly_revenue, main.customer_segments
AI Tables	Special Views where AI adds intelligent columns (classifications, extractions, etc.). Lives in main schema.	main.expense_categorization, main.churn_risk_scores

How do I import data?

1. Click "Import Data" in your Workbook
2. Choose your data source:
   • Upload CSV/Excel: Drag-and-drop or browse
   • Connect tools: (coming soon: Google Sheets, Airtable, etc.)
3. Preview your data to confirm it looks correct
4. Your Source appears in the sidebar

Your original data becomes a Source in the sources schema.

Coming soon: Live database connections (Snowflake, BigQuery, Databricks, Clickhouse, Redshift).

Can I try Shadowfax without my own data?

Yes! We have sample datasets for common use cases:

• E-commerce: Orders, customers, products
• SaaS: Users, subscriptions, usage events
• Marketing: Campaigns, leads, conversions
• Finance: Transactions, budgets, departments

Each tutorial includes downloadable CSV files and guided prompts.

How long does it take to learn?

10 minutes to understand the basics (Workbook, Sources, Views, @mentions).

15-20 minutes per domain tutorial to learn real analytical workflows.

Hours saved once you start using it for your actual work.

---

Working with the AI Agent

How do I write good prompts?

Follow the C.L.E.A.R. framework:

• Concise: Get to the point. @[orders] Show monthly revenue not "I was wondering if maybe you could..."
• Logical: Break complex requests into steps
• Explicit: State exactly what you want (columns, calculations, filters)
• Adaptive: Iterate and refine based on results
• Reflective: Learn from what works

Always use @mentions to tell the AI which data to work with.

See the Prompt Engineering Guide for advanced techniques.

What are @mentions?

@mentions tell the AI which data to work with. Type @ and you'll see an autocomplete list of your Sources and Views.

@[orders] Calculate total revenue
@[customers] @[orders] Join these and calculate customer lifetime value
@[monthly_revenue] Add a year-over-year comparison column

Rules:

• Use @[source_name] for Sources
• Use @[view_name] for Views you've already created
• Use multiple @mentions to join tables
• Always @mention at the start of your prompt

What are slash commands?

Shadowfax has four special commands that change how the AI works:

Command	What It Does	When to Use
/plan	AI shows you a plan before executing	Complex multi-step analyses
/visualize	Activates specialized chart-building mode	Creating any visualization
/recommendations	AI suggests logical next steps	When you're stuck or exploring
/taxonomy	Discovers and proposes data categories	Classifying text or creating classification AI tables

Example:

/plan @[sales_data] @[customer_data]
Create a comprehensive customer segmentation analysis

Can the AI make mistakes?

Yes. Like any AI, Shadowfax can misunderstand or make incorrect assumptions.

How to reduce mistakes:

• Be explicit in your prompts (don't assume the AI knows your intent)
• Use /plan for complex work to review the approach first
• Always inspect Views to verify the logic
• Check the SQL and data preview

How to catch mistakes:

• Click any View to see the SQL and data
• Look for unexpected row counts or values
• Verify calculations make sense
• Ask: "Show me the SQL for [view_name]"

If something's wrong:

This doesn't look right. The revenue totals are too high.
I think you're including refunds. Please filter to status = 'completed' only.

Be specific about what's wrong, and the AI will fix it.

What if the AI doesn't understand me?

1. Add more context: Be more explicit about what you want
2. Use @mentions: Make sure you're referencing the right data
3. Break it down: Split complex requests into smaller steps
4. Show an example: "I want output like: [describe format]"
5. Ask for clarification: "What approach are you planning to use?"

Unclear:

Analyze customers

Clear:

@[customers] @[orders]
Calculate total spent, order count, and average order value for each customer.
Then segment customers into High Value (>$1000 spent), Medium ($500-$1000), and Low (<$500).

How do I reference a View in another prompt?

Use @[view_name] just like you'd reference a Source:

@[monthly_revenue] Add a 3-month moving average column

The AI knows about all your Views and can build on top of them.

Can I edit the SQL of a View directly?

Yes, but only if you want to. Most users never need to edit SQL directly—the AI handles it.

To edit SQL:

1. Click on the View in your sidebar
2. Click "Edit" or "Show SQL"
3. Modify the SQL
4. Save

Better approach for most users:

@[view_name] This view has a mistake. Please fix [describe what's wrong]

Let the AI rewrite it. This ensures:

• Proper syntax
• Correct references
• Updated dependencies

How do I see what a View does?

Click on any View in your Workbook Objects sidebar. You'll see:

• SQL code: The SELECT statement that creates the View
• Data preview: Sample rows (10-50 rows)
• Schema: Column names and types
• Classification badge: What type of transformation it is (Aggregate, Combine, etc.)
• Dependencies: What Views or Sources it depends on

What are View classifications?

Every View is tagged with a classification that describes what type of transformation it performs:

• SELECT_FILTER: Filtering rows or columns
• COMBINE: Joining tables or combining data
• CONVERT_TYPES: Type conversions (CAST, date parsing)
• CALCULATE_COLUMNS: Adding or modifying columns
• AGGREGATE: GROUP BY operations (sum, count, avg)
• CALCULATE_GROUPWISE: Window functions (rank, row_number, moving averages)
• RESHAPE: Pivoting, unpivoting, unnesting
• PRESENT: Final presentation layer (selecting and ordering output)
• RECURSION: Recursive queries (hierarchies, graphs)

These badges help you understand what each View does at a glance.

How do I delete a View I don't need?

Ask the AI:

Delete the [view_name] View—I don't need it anymore

Or click on the View and look for a delete option in the UI.

Important: If other Views depend on this View, the AI will warn you and ask for confirmation.

---

Understanding Views

What exactly is a View?

A View is a SQL SELECT statement that transforms data. Think of it as a saved query that creates a virtual table.

Example View SQL:

SELECT
  DATE_TRUNC('month', order_date) AS month,
  SUM(amount) AS total_revenue
FROM sources.orders
WHERE status = 'completed'
GROUP BY month
ORDER BY month

Key properties:

• Views don't store data—they're live queries
• Views update automatically when underlying data changes
• Views can reference other Views
• Each View is reusable via @[view_name]

Where do Views live?

Views live in the main schema of your Workbook database.

Full naming:

• Source: sources.orders
• View: main.monthly_revenue
• AI Table: main.churn_risk (also in main schema)

In prompts, you just use @[monthly_revenue]—no need for the schema prefix.

What's the reactive system?

The reactive system means Views automatically update when upstream data changes.

Example:

1. You create cleaned_orders (filters bad data from sources.orders)
2. You create monthly_revenue (aggregates from cleaned_orders)
3. You create revenue_growth (calculates growth from monthly_revenue)

Dependency chain: sources.orders → cleaned_orders → monthly_revenue → revenue_growth

If you modify cleaned_orders, both monthly_revenue and revenue_growth automatically recalculate.

Benefits:

• No broken formulas
• No manual updates
• Fix upstream, everything downstream updates
• Experiment freely

If I change a Source, do Views update?

Yes, automatically.

If you:

• Upload new data to replace a Source
• Modify data in a connected database
• Refresh a Source

All Views that depend on that Source (directly or indirectly) automatically recalculate with the new data.

Can Views reference other Views?

Yes! This is how you build multi-step analytical pipelines.

Example:

@[orders] Clean the data: remove nulls, filter to completed orders

→ Creates cleaned_orders

@[cleaned_orders] Calculate monthly revenue totals

→ Creates monthly_revenue (which references cleaned_orders)

@[monthly_revenue] Add month-over-month growth rate

→ Creates revenue_growth (which references monthly_revenue)

Each View builds on previous work. This keeps logic organized and reusable.

What do the View badges mean?

Badges show the classification of each View—the type of transformation it performs.

Common badges:

• Aggregate: Uses GROUP BY to roll up data
• Combine: Joins multiple tables
• AI: AI Table with LLM-generated columns
• Filter: Filters rows or selects columns
• Calculate: Adds or modifies columns

These help you understand your analytical pipeline at a glance.

How do I see View dependencies?

Click the Graph icon to see your dependency graph:

• Nodes: Sources and Views
• Arrows: Dependencies (A → B means "B depends on A")
• Hover: See View details
• Click: Navigate to that View

This helps you understand how your analysis flows from raw data to insights.

Can I export Views as SQL?

Yes. Click on a View and look for "Export SQL" or "Copy SQL" option.

You can then:

• Run the SQL in your own database
• Share with technical team members
• Document your methodology
• Port to other analytics tools

---

AI Tables

What are AI Tables?

AI Tables are special Views where AI adds intelligent columns using large language models (LLMs).

Use AI Tables for tasks SQL can't handle:

• Classification: Categorize expenses, prioritize tickets
• Extraction: Pull entities from unstructured text
• Sentiment analysis: Analyze customer feedback tone
• Summarization: Create brief summaries of long text
• Scoring: Rate based on rubrics (quality scores, risk levels)

Key difference from Views:

• Views use SQL (deterministic, fast)
• AI Tables use LLMs (semantic understanding, flexible)

When should I use an AI Table vs regular View?

Task	Use
Filtering, joining, aggregating, calculating	Regular View (SQL)
Categorizing messy text (e.g., expense types)	AI Table
Extracting structured data from unstructured text	AI Table
Sentiment or intent classification	AI Table
Mathematical calculations	Regular View (SQL)
Summarization or paraphrasing	AI Table

Rule of thumb: If a human would need to "read and understand" the data to do the task, use an AI Table. If it's logical/mathematical, use a regular View.

How do I create an AI Table?

Prompt:

@[transactions]
Create an AI Table that categorizes each transaction into expense types:
Software, Travel, Office Supplies, Marketing, or Other.
Include a confidence score and reasoning.

The AI will create:

• Input columns: Relevant context (vendor, memo, amount)
• AI output columns: Your requested outputs (category, confidence, reasoning)
• A prompt (instructions for the LLM)

Important: The AI Table is created but AI columns are NULL until you refresh it.

Why are AI columns NULL?

AI columns start as NULL because AI processing must be triggered manually. Only you (the user) can refresh an AI Table—the agent can't do it automatically.

Why manual?

• AI processing costs money
• You control when to run it
• You might want to filter rows first (process only relevant data)

To populate AI columns: Click the Refresh button on the AI Table.

How do I refresh an AI Table?

1. Click on the AI Table in your sidebar
2. Click the "Refresh" button
3. Wait while the AI processes rows (may take a few seconds to minutes depending on row count)
4. AI output columns will populate

After refresh, your AI-generated columns will have values!

What can AI Tables do?

Common use cases:

Classification:

• Categorize expenses (Software, Travel, etc.)
• Prioritize support tickets (High/Medium/Low)
• Classify leads (Hot/Warm/Cold)
• Tag content by topic

Extraction:

• Extract product names from messy descriptions
• Pull dates, amounts, or entities from text
• Parse addresses into structured fields

Analysis:

• Sentiment analysis of customer feedback
• Intent detection from chat transcripts
• Quality scoring based on rubrics

Generation:

• Summarize long text into brief descriptions
• Generate personalized recommendations
• Create reasons or explanations for categorizations

---

Data & Sources

What data formats can I import?

Direct upload:

• CSV files
• Excel files (.xlsx)
• Parquet files

Coming soon - Database connections:

• Snowflake
• BigQuery
• Databricks
• Clickhouse
• Redshift

Coming soon - Tools:

• Google Sheets
• Airtable
• APIs

Can I connect to live databases?

Coming soon! We're building live database connections with the following databases in priority order:

1. Snowflake - Data warehouse optimized for cloud analytics
2. BigQuery - Google's serverless data warehouse
3. Databricks - Unified data and AI platform
4. Clickhouse - Fast OLAP database for analytics
5. Redshift - AWS data warehouse

How it will work:

1. Provide connection credentials
2. Select which tables to import as Sources
3. Choose refresh schedule (manual, hourly, daily)
4. Views automatically update when Sources refresh

Security: Credentials will be encrypted and stored securely.

What's the difference between uploading CSV vs connecting a database?

Aspect	CSV Upload	Database Connection
Data storage	Copied into Shadowfax	Stays in your database
Updates	Manual re-upload	Automatic refresh
Size limits	Limited by upload size	Can handle larger datasets
Best for	One-time analysis, small datasets	Ongoing dashboards, live data

Note: Database connections are coming soon (Snowflake, BigQuery, Databricks, Clickhouse, Redshift). Currently, only CSV/Excel/Parquet uploads are available.

Where is my data stored?

Uploaded data (CSV/Excel):

• Stored securely in Shadowfax's cloud infrastructure
• Encrypted at rest and in transit
• Isolated per workspace (other users can't see your data)

Connected databases (coming soon):

• Data stays in your database
• Shadowfax queries it as needed
• Credentials encrypted

See our Security & Privacy Policy (placeholder link) for details.

Can I have multiple Sources in one Workbook?

Yes! A Workbook can have as many Sources as you need.

Common patterns:

• Multiple related tables (orders, customers, products)
• Different data sources (database + CSV uploads)
• Historical data + live data

Use @mentions to work with any Source:

@[orders] @[customers] @[products]
Join all three and create a complete sales analysis

How does Schema Discovery work?

When you import data, Shadowfax automatically:

1. Detects data types (dates, numbers, text)
2. Identifies relationships (potential foreign keys)
3. Builds a schema graph showing how tables connect

Click the Graph tab to see the visual schema:

Why this matters:

• The AI understands how to join your tables
• You can see relationships at a glance
• Reduces the need to explain your data structure

Can I update a Source with new data?

For uploaded files:

• Re-upload the file with the same name
• Shadowfax will replace the data
• All Views update automatically

For database connections (coming soon):

• Click "Refresh" to pull latest data
• Or set an automatic refresh schedule

---

Visualizations

What chart types can I create?

Shadowfax uses Vega, giving the AI the ability to create any chart type you can describe. The more precise your prompt, the more detailed your visualization.

Common chart types:

• Bar charts (horizontal, vertical, grouped, stacked)
• Line charts, area charts
• Scatter plots, bubble charts
• Pie charts, donut charts
• Heatmaps
• Histograms, box plots
• Treemaps, sunburst diagrams
• Geographic maps (choropleth)
• Network diagrams
• And many more

How do I create a visualization?

Use the /visualize command:

/visualize @[monthly_revenue]
Create a line chart showing revenue over time with a trend line

The AI will:

1. Create your chart
2. Render the visualization
3. Let you iterate and refine

Iterate:

Add data labels and format Y-axis as currency
Make the line blue with a gradient fill
Add annotations on the two highest revenue months

Can I customize colors, labels, axes?

Absolutely. Just ask:

Change bar colors to blue gradient
Add data labels showing values
Format Y-axis as percentages with 1 decimal place
Rotate X-axis labels 45 degrees
Use log scale for Y-axis
Add grid lines
Change title to "Q4 Revenue Performance"
Add a subtitle

The AI will update the chart.

How do I export charts for presentations?

Export options (look for export button on visualizations):

• PNG image (high resolution)
• SVG vector (scales without quality loss)
• JSON (for developers)

For presentations:

• Export as PNG for slides
• Export as SVG for print materials
• Copy and paste directly into documents

Can I create dashboards?

Yes. You can create multi-chart dashboards by asking the AI to combine visualizations:

Create a dashboard with:
- KPI cards showing total revenue, order count, average order value
- Line chart of daily revenue trend
- Bar chart of top 10 products
- Pie chart of revenue by category

The AI will lay out multiple visualizations together.

---

Collaboration & Sharing

How do I share a Workbook?

Click the Share button in your Workbook and:

• Add team members by email
• Set permissions (Viewer, Editor, Admin)
• Generate a shareable link (optional)

Can multiple people work in the same Workbook?

Yes. Workbooks support real-time collaboration:

• See who else is viewing
• Changes sync automatically
• Each person can work independently (Views don't conflict)

Best practices:

• Communicate about major changes
• Use descriptive View names
• Don't delete Views others might be using

Can I export my Views as SQL files?

Yes. For each View:

1. Click the View
2. Look for "Export SQL" or "Copy SQL"
3. Save as .sql file

You can export your entire analytical pipeline as SQL scripts.

Can I export data as CSV?

Yes. For any View or Source:

1. Click to open
2. Look for "Export" button
3. Choose CSV format
4. Download

Use cases:

• Share results with stakeholders
• Import into Excel
• Use in other tools

How do I transfer Workbook ownership?

Go to Workbook settings and look for "Transfer Ownership" option. You'll need admin permissions.

---

Troubleshooting

The View has wrong calculations—how do I debug?

Step-by-step debugging:

1. Click the View to see SQL and data preview
2. Check the SQL logic:
   • Are the right tables joined?
   • Are filters correct?
   • Is the calculation formula right?
3. Check intermediate steps:
   • If this View depends on other Views, check those first
   • Look at the dependency graph
4. Provide specific feedback:

   @[view_name] This calculation is wrong.
   The issue is [specific problem].
   Please fix by [specific solution].

Example:

@[monthly_revenue] The totals are too high.
You're summing 'amount' which is in cents, not dollars.
Please divide by 100 to convert to dollars.

My Workbook is slow—what do I do?

Common causes & solutions:

Large datasets:

• Filter early (don't process unnecessary rows)
• Aggregate before joining (reduce data volume)
• Use indexed columns in filters and joins

Complex Views:

• Break into smaller, simpler Views
• Avoid SELECT * (select only needed columns)
• Check for Cartesian joins (missing join conditions)

Ask the AI:

My [view_name] View is slow. Can you optimize it?

A View isn't updating—why?

Possible causes:

1. Manual refresh needed (for some data sources)

   • Click "Refresh" on the Source

2. View reference is cached

   • Click "Refresh" on the specific View

3. Dependency issue

   • Check the dependency graph
   • Make sure upstream Views are updated

Ask the AI:

Why isn't [view_name] showing the latest data?

I deleted a View by accident—can I undo?

Check Workbook history:

• Look for "History" or "Version History" in your Workbook
• Restore from a previous state

If no history:

• Views are SQL queries, so if you remember what it did, you can recreate it
• Ask the AI: "Recreate the [view_name] View that calculated [what it did]"

Prevention:

• The AI will warn you before deleting Views that have dependencies
• Consider naming Views clearly so you don't delete wrong ones

The AI lost context—how do I help it?

The AI doesn't have infinite memory. If you've had a long conversation, it might forget earlier context.

Solutions:

1. Use @mentions (always explicit about which data):

   @[customer_segments] Add a visualization showing segment distribution

2. Reference Views by name:

   Update the monthly_revenue View to exclude refunds

3. Start a new conversation if needed (your Views persist)

4. Add Knowledge documents with persistent context (see Prompt Engineering Guide)

SQL error in a View—what now?

The AI usually catches SQL errors, but if one appears:

1. Click the View to see the SQL
2. Read the error message (usually shows what's wrong)
3. Ask the AI to fix it:

   The [view_name] View has a SQL error: [paste error message]
   Please fix it

Common errors:

• Column doesn't exist (typo in column name)
• Ambiguous column (same column in multiple tables—need to specify which)
• Type mismatch (trying to do math on text, etc.)

The AI will understand the error and rewrite the View correctly.

How do I see what went wrong?

Check the activity log in your Workbook:

• See all actions the AI took
• See which Views were created/modified/deleted
• See errors and how they were resolved

This helps you understand the agent's reasoning and catch issues.

---

Support

How do I get help?

Resources:

1. This documentation - Search for your question
2. Prompt Engineering Guide - Best practices
3. Use Cases - Examples and inspiration
4. Community forum - Ask the community (placeholder link)
5. Email support - [email protected] (placeholder email)

Response times vary by plan (Enterprise gets priority support).

Where can I learn more?

Advanced techniques:

• Prompt Engineering Guide
• Tips & Tricks

Inspiration:

• Use Cases
• Features

How do I request features?

We'd love to hear your ideas!

Ways to request features:

1. Email: [email protected] (placeholder)
2. Community forum: Vote on feature requests (placeholder link)
3. In-app feedback: Look for feedback button in the UI

Enterprise customers can work directly with their account manager for custom features.