Troubleshooting

For Administrators

"Cannot resolve join plan" Error

Problem: When users select fields from multiple datasets, they see an error about unreachable datasets.

Causes:

• No relationship exists between the selected datasets
• Relationship is disabled (not set to auto-join)
• Datasets are in separate disconnected graphs

Solution:

1. Check that relationships exist between all selected datasets
2. Verify relationships have "Auto-Join Enabled" checked
3. Use the Relationships tab to add missing relationships
4. Run AI Discovery to find missing relationships

Fields Not Showing in Dashboard

Problem: Users can't see certain fields when building charts.

Causes:

• Fields are marked as hidden
• Dataset is not added to the domain
• Field visibility is turned off

Solution:

1. In the Datasets tab, edit the dataset
2. Check the visibility icon (eye) for each field
3. Ensure fields you want visible are not hidden

Virtual Dataset Preview Fails

Problem: Clicking Preview Columns returns an inline SQL error instead of a column list.

Causes:

• Invalid SQL syntax for the target dialect
• Trailing semicolon -- Semaphor wraps your SQL as a subquery, so ; breaks it
• References to tables or columns that don't exist on the selected connection
• Unqualified table references that don't resolve without a default schema

Solution:

1. Remove any trailing ; from the SQL.
2. Fully qualify tables using schema.table (e.g. analytics.orders) or database.schema.table where your dialect requires it. SQL Dataset mode does not apply a search_path or session schema.
3. Verify referenced tables exist on the dataset's owning connection.
4. Try the query in a SQL client against the same connection. If it fails there, fix it there first.

"Preview required" When Saving SQL Changes

Problem: You edited the SQL in an existing virtual dataset and Apply is disabled or shows a "Preview required" message.

Cause: Semaphor requires a fresh Preview Columns after any SQL change before it will let you apply the edit. This protects you from saving a query that no longer returns the columns your fields depend on.

Solution:

1. Click Preview Columns in the edit dialog.
2. Review the inline reconciliation -- newly returned columns, still-resolvable fields, and unresolved fields.
3. Select which new columns to add and which unresolved fields to remove.
4. Click Apply, then Save on the domain.

Unqualified Table Reference Fails at Runtime

Problem: The SQL runs in your database client but fails inside Semaphor with a "table not found" or "relation does not exist" error.

Cause: Your client has a default schema or search_path set in the session. Semaphor's SQL Dataset mode intentionally does not apply one -- the dataset SQL must resolve on its own.

Solution:

Fully qualify every table reference in the SQL:

-- Works in a session with search_path=analytics, fails in Semaphor
SELECT customer_id, SUM(amount) AS revenue
FROM orders
GROUP BY customer_id

-- Works in Semaphor
SELECT customer_id, SUM(amount) AS revenue
FROM analytics.orders
GROUP BY customer_id

Unresolved Fields on a Virtual Dataset

Problem: One or more fields on your virtual dataset show an unresolved indicator.

Cause: The semantic field no longer maps to a column returned by the dataset's current SQL. This usually happens after a SQL edit renames or drops a column, or after the underlying source changes.

Solution: Pick whichever fits:

• Repair the SQL. Open the edit dialog, fix the SELECT list so the expected column comes back, click Preview Columns, then Apply and Save.
• Remove the field. Open the edit dialog, click Preview Columns, select the unresolved field in the "No longer returned" list, then Apply and Save.
• Leave it for now. Unresolved indicators are session-local and never block domain Save. They're recomputed each time you run Preview, Fetch, or Sync.

General Virtual Dataset SQL Tips

• Virtual datasets are embedded as subqueries at query time, so both subqueries and CTEs (WITH ... AS (...)) are supported.
• Avoid trailing semicolons.
• Use dialect-valid SQL for the owning connection's database.
• Each virtual dataset is bound to exactly one connection -- cross-connection SQL is not supported.

See Virtual Datasets for the full authoring guide.

AI Discovery Returns No Suggestions

Problem: AI relationship discovery completes but finds no relationships.

Causes:

• Domain has only one dataset
• Field names don't follow common patterns
• All relationships already exist
• Insufficient data for analysis

Solution:

1. Ensure you have at least 2 datasets in the domain
2. Manually create one relationship as an example
3. Use conventional field names (e.g., customer_id, order_id)
4. Add more datasets to provide context for the AI

Slow Query Performance

Problem: Queries using the domain take a long time to run.

Causes:

• Complex multi-hop joins
• Virtual datasets with expensive SQL
• Missing database indexes
• Too many fields selected

Solution:

1. Review the generated SQL in the query log
2. Ensure join keys are indexed in your database
3. Simplify virtual dataset SQL
4. Create intermediate materialized views for complex calculations
5. Limit the number of fields users can select

Duplicate Relationships

Problem: Multiple relationships exist between the same two datasets.

Causes:

• Different join paths for different use cases
• AI discovery created duplicates
• Composite keys defined separately

Impact: May cause ambiguous join resolution

Solution:

1. Review all relationships between the dataset pair
2. Delete true duplicates (exact same join keys)
3. For different join paths, set different priorities
4. Disable auto-join for less common paths

Relationship Not Being Used

Problem: You created a relationship but it's not being used in auto-join resolution.

Causes:

• Auto-join is disabled for the relationship
• Relationship is marked as inactive
• Another relationship has higher priority

Solution:

1. Edit the relationship and ensure "Auto-Join Enabled" is checked
2. Verify "Is Active" is set to true
3. Check join priority - higher numbers are used first
4. Save the domain after making changes

Cache Invalidation Issues

Problem: Relationship changes don't take effect immediately.

Cause: Domain cache not invalidated after updates.

Solution:

1. Click "Save" in the domain editor after making changes
2. Wait a few seconds for cache to clear
3. Refresh the dashboard card to see updated relationships
4. If issues persist, contact your system administrator

For End Users

"Why Is a Field Grayed Out?"

Problem: A field appears grayed out and cannot be dragged.

Cause: The field's dataset has no relationship path to your currently selected datasets.

What It Means:

• You've selected fields from dataset A
• The grayed-out field is from dataset B
• No relationship exists between A and B (either direct or indirect)

Solutions:

1. Check with your admin: The relationship might be missing
2. Clear your selection: Click "Clear All" and start with the grayed-out field's dataset as base
3. Choose a different field: Find a field from a related dataset instead
4. Request relationship: Ask your admin to add the relationship if it should exist

"What Does 'Auto-Resolved Join' Mean?"

Meaning: Semaphor automatically created the necessary joins between your selected datasets based on pre-defined relationships.

Why It's Good:

• You don't need to know SQL or understand joins
• Relationships are governed and consistent across all analyses
• Reduces errors from manual join configuration

How It Works:

1. Admin defines relationships in the semantic domain
2. You select fields from multiple datasets
3. Semaphor finds the shortest join path
4. Query executes with joins automatically applied
5. Results return with auto-join metadata

"Why Do I See a Yellow Indicator on Some Fields?"

Meaning: The field requires a multi-hop join (2-hop) to reach from your base dataset.

Example:

• Base dataset: orders
• Yellow field: country_name from countries
• Join path: orders → stores → countries

Is It Safe to Use?

• Yes! Multi-hop joins work just like direct joins
• They may be slightly slower on large datasets
• Review the auto-join panel to understand the join path

When to Be Cautious:

• Very large fact tables with complex hierarchies
• If query performance becomes an issue
• Ask your admin if you're unsure about the relationship

"How Do I Know Which Datasets Are Being Joined?"

Answer: Check the Auto-Resolved Joins panel in the Visual tab.

Where to Find It:

• In the Visual tab of the card editor
• Below the field list on the left side
• Shows a badge with the number of joins (e.g., "Auto-Resolved Joins [2]")
• Click to expand for full details

What It Shows:

• All datasets involved in the query
• Join type (INNER, LEFT, RIGHT, FULL)
• Join conditions (which fields match)
• Join sequence (order of joins)

Alternative: Hover over any field in the field list to see its join path tooltip.

"Can I Override Auto-Resolved Joins?"

Short Answer: Not directly from the field selection interface.

Explanation:

• Auto-resolved joins use the relationships defined in the semantic domain
• Join types and keys are governed by the admin's configuration
• This ensures consistency across all users and analyses

If You Need Different Join Logic:

1. Ask your admin to adjust the relationship (join type, keys, priority)
2. Use Manual Join Mode (if your deployment supports it) in the Joins tab
3. Switch to SQL mode and write custom SQL (if you have permissions)
4. Create a virtual dataset with pre-joined data

"What Happens If I Select Fields from Unrelated Datasets?"

Result: You'll get an error message: "Cannot resolve join plan"

Error Message Example:

⚠️ Cannot resolve join plan

The following datasets cannot be joined to your selection:
- employees (no relationship path from orders)

Please select fields from related datasets or ask your
administrator to add missing relationships.

What This Means:

• You tried to combine datasets with no defined relationship
• Semaphor cannot automatically determine how to join them
• The datasets might be completely unrelated (e.g., Orders and Employee Payroll)

Solutions:

1. Remove unreachable fields: Deselect fields from the unreachable dataset
2. Start over: Clear selection and choose related datasets
3. Request relationship: If datasets should be related, ask your admin to add it
4. Separate visualizations: Create two cards for unrelated datasets

Query Results Don't Match Expectations

Problem: The data in your chart doesn't look right.

Possible Causes:

• Join type is incorrect (INNER vs LEFT)
• Multi-hop join is filtering or duplicating rows
• Wrong relationship being used

Debugging Steps:

1. Check the Auto-Join Panel:

   • Expand to see all joins
   • Verify join types (INNER, LEFT, RIGHT, FULL)
   • Ensure join keys are correct

2. Verify Join Type:

   • LEFT JOIN: Includes all records from left side
   • INNER JOIN: Only includes matching records
   • Ask your admin if the join type should be different

3. Check Row Counts:

   • Compare row count with expected results
   • Look for duplicates (many-to-many joins)
   • Look for missing data (INNER join filtering)

4. Review Relationships:

   • Ask your admin to verify relationship cardinality
   • Check if composite keys are needed
   • Ensure relationship is using correct fields

Fields Show Wrong Data Types

Problem: A number field shows as text, or dates aren't formatted correctly.

Cause: Field configuration in the semantic domain.

Solution:

1. Ask your admin to check the field configuration
2. Verify the field's data type setting (String, Number, Date, etc.)
3. For dates, check the date format configuration
4. For measures, verify the aggregate function is set correctly

Can't Find Expected Field

Problem: You can't find a field you expect to see in the field list.

Possible Causes:

• Field is hidden by admin
• Field name is different than expected
• Field is in a different dataset
• Dataset hasn't been added to the domain

Solutions:

1. Use the search bar: Search for the field by name or description
2. Check different datasets: Expand all dataset groups to browse
3. Ask your admin: The field might be hidden or named differently
4. Request addition: If the field should exist, ask admin to add it

Slow Dashboard Loading

Problem: Cards using semantic domains load very slowly.

Causes:

• Complex multi-hop joins
• Large datasets without proper indexing
• Too many fields in visualization
• Multiple cards with different join patterns

What You Can Do:

1. Simplify visualizations: Use fewer fields when possible
2. Avoid unnecessary multi-hop joins: Stick to direct relationships when possible
3. Add filters: Filter data to reduce query size
4. Report to admin: Performance issues should be investigated by admin

What Your Admin Can Do:

• Add database indexes on join keys
• Create materialized views for common queries
• Optimize virtual dataset SQL
• Review query logs for slow joins

Common Error Messages

"Domain or current version not found"

Meaning: The semantic domain you're trying to use doesn't exist or isn't published.

Solution: Contact your admin to ensure the domain is published and accessible.

"Unauthorized"

Meaning: You don't have permission to access this semantic domain.

Solution: Contact your admin to request access to the domain.

"Cannot resolve join plan"

Meaning: Semaphor cannot find a relationship path between your selected datasets.

Solution: Either select fields from related datasets only, or ask your admin to add the missing relationship.

"Invalid field configuration"

Meaning: A field in your visualization has incorrect settings.

Solution: Remove the problematic field and try a different one, or ask your admin to fix the field configuration.

Getting Help

If you're still experiencing issues:

For Administrators:

1. Check the domain configuration in the Code Editor tab
2. Review query logs for error details
3. Test relationships with simple queries first
4. Contact Semaphor support with error details

For End Users:

1. Take a screenshot of the error message
2. Note which fields you were trying to use
3. Share with your domain administrator
4. Try a simpler query to isolate the issue

Best Practices to Avoid Issues

For Administrators:

• ✅ Test all relationships after creation
• ✅ Use AI discovery as a starting point, then refine
• ✅ Document relationship purposes in descriptions
• ✅ Set appropriate join types (LEFT vs INNER)
• ✅ Index all join key fields in your database
• ✅ Review and clean up unused relationships periodically

For End Users:

• ✅ Start with simple queries and build incrementally
• ✅ Check field states before dragging (green/yellow/gray)
• ✅ Review auto-join panel after running queries
• ✅ Ask admin for help when encountering unreachable fields
• ✅ Report performance issues to your admin
• ✅ Save working queries for future reference

Still need help? Contact your Semaphor administrator or check the Admin Setup Guide and User Guide for more information.