Skip to main content

Preferred Tables

Preferred tables allow each user to personally mark specific tables that the AI should prioritize when generating SQL queries. Marked tables are sent to the LLM with full metadata — including columns, data types, and business descriptions — so the AI understands exactly what data is available and uses it first.

Overview​

When you ask a natural language question, Actyze's AI needs to decide which tables to use. Preferred tables help by:

  • Pinpointing the exact tables most relevant to your work
  • Sending full column context to the LLM so it builds better SQL
  • Reducing ambiguity when multiple similar tables exist
  • Personalizing results to your role and data patterns

This is a user-level setting — each user has their own preferred tables list, up to 25 tables by default (configurable by administrators).

How It Works​

Without Preferred Tables​

Query: "Show me customer revenue"

AI uses semantic search over all accessible tables:
- sales.public.customers (score: 0.75)
- analytics.mart.customer_revenue (score: 0.73)
- staging.temp.customer_data (score: 0.71)

Selected: sales.public.customers (highest score)
→ May not be the table you actually want

With Preferred Tables​

Query: "Show me customer revenue"

User has marked as preferred: analytics.mart.customer_revenue

AI receives:
★ analytics.mart.customer_revenue (PREFERRED)
  Columns: customer_id (bigint), customer_name (varchar),
           total_revenue (decimal), region (varchar), ...

AI selects: analytics.mart.customer_revenue ✓
→ Uses your preferred table with full column knowledge

Setting Preferred Tables​

Via User Interface​

Step 1: Open Schema Optimize

  1. Go to Data Intelligence → Schema Optimize
  2. Browse the database tree on the left

Step 2: Mark a Table as Preferred

  1. Click any table name in the tree
  2. In the right panel, toggle "Mark as Preferred"
  3. Click Save

A ⭐ star icon appears next to preferred tables in both Schema Optimize and the Query page schema sidebar, giving you instant visual confirmation.

Step 3: Bulk Preferred Mode

To mark many tables at once:

  1. Click "Bulk Preferred" button at the top of Schema Optimize
  2. Checkboxes appear on all table rows
  3. Select tables individually, or use "Select all tables" under a schema
  4. Click "Mark Preferred" or "Remove Preferred" in the action bar at the bottom

Via API​

Add a Preferred Table:

curl -X POST https://your-actyze.com/api/preferences/preferred-tables \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog": "postgres",
    "schema_name": "analytics",
    "table_name": "customer_revenue"
  }'

Add Multiple Tables (Bulk):

curl -X POST https://your-actyze.com/api/preferences/preferred-tables/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": [
      {"catalog": "postgres", "schema_name": "analytics", "table_name": "customer_revenue"},
      {"catalog": "postgres", "schema_name": "analytics", "table_name": "monthly_summary"}
    ]
  }'

View Your Preferred Tables:

curl -X GET https://your-actyze.com/api/preferences/preferred-tables \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

[
  {
    "id": "pref-uuid-1",
    "catalog": "postgres",
    "database_name": "postgres",
    "schema_name": "analytics",
    "table_name": "customer_revenue",
    "full_name": "postgres.analytics.customer_revenue",
    "table_metadata": "Primary revenue reporting table for the analytics team",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
]

Remove a Preferred Table:

curl -X DELETE https://your-actyze.com/api/preferences/preferred-tables/{preference_id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Remove Multiple Tables (Bulk):

curl -X DELETE https://your-actyze.com/api/preferences/preferred-tables/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preference_ids": ["pref-uuid-1", "pref-uuid-2"]
  }'

The 25-Table Limit​

By default, each user can mark up to 25 tables as preferred. This limit exists because each preferred table adds its full column list and metadata to the LLM prompt, consuming tokens.

Administrators can adjust this limit via the MAX_PREFERRED_TABLES environment variable in docker-compose.yml (Docker) or nexus.env.maxPreferredTables in values.yaml (Kubernetes/Helm).

Token budget guidance: If raising the limit, also increase EXTERNAL_LLM_MAX_TOKENS:

Preferred Tables LimitRecommended Max Tokens
10–25 (default)4096 (default)
26–406000
41–508000

What Gets Sent to the AI​

For each preferred table, the AI receives:

★ postgres.analytics.customer_revenue (PREFERRED)
  Description: Primary revenue reporting table for the analytics team
  Columns:
    - customer_id (bigint)
    - customer_name (varchar) — Full legal name of the customer
    - total_revenue (decimal) — Lifetime revenue in USD
    - region (varchar) — Geographic region code
    - last_purchase_date (date)
    - segment (varchar) — Customer tier: enterprise, smb, consumer

The metadata descriptions (table and column descriptions) come from your organization's Metadata Descriptions settings and significantly improve AI accuracy.

Use Cases​

Scenario 1: Team-Specific Tables​

Problem: Your analytics team has its own reporting tables, but the AI sometimes picks staging or raw tables instead.

Solution: Mark your team's canonical reporting tables as preferred.

Result:

Query: "Show monthly revenue by region"
Uses: postgres.analytics.monthly_revenue_by_region ★
Over: postgres.staging.raw_transactions

Scenario 2: Production vs Staging​

Problem: You always want production data, not staging.

Solution: Mark all production tables as preferred.

Result:

Query: "Show all customers"
Uses: postgres.production.customers ★
Unless you explicitly say "show me staging customers"

Scenario 3: Complex Domain Tables​

Problem: A table has 80 columns but only 10 are relevant to your work. The AI doesn't always choose the right columns.

Solution: Mark the table as preferred. The AI receives all column names and types upfront, plus any descriptions you've added via Metadata, so it can make much better column selections.

Rules & Constraints​

  • Table-level only: Preferred functionality applies to individual tables, not entire schemas or databases
  • User-specific: Your preferred tables are private — other users have their own lists
  • Cannot mark hidden tables: Tables hidden by an admin (excluded from the schema) cannot be marked as preferred
  • Hiding removes preference: If a previously-preferred table is hidden by an admin, the preference is automatically removed
  • Limit enforced server-side: The MAX_PREFERRED_TABLES limit is enforced by the backend even for bulk operations

Visual Indicators​

  • ⭐ in Query page sidebar: Preferred tables show a gold star next to their name in the schema tree on the Query page
  • ★ in Schema Optimize: Preferred tables are starred in the Schema Optimize tree
  • Counter in Schema Optimize: Shows (X/25 tables marked) with color coding: green (plenty of room), yellow (>80% full), red (at limit)

Managing Preferences​

View All Preferred Tables​

In the Schema Optimize right panel, a "Preferred Tables" section shows all currently preferred tables with their names and the option to remove them.

Remove a Preference​

Single table:

  1. Click the table in Schema Optimize
  2. Toggle off "Mark as Preferred"
  3. Click Save

Bulk removal:

  1. Enter Bulk Preferred mode
  2. Select tables to unmark
  3. Click "Remove Preferred"

Regular Review​

Review your preferred tables periodically:

  • Remove tables you no longer use frequently
  • Add newly important tables
  • Keep the list focused (10–15 tables is typically sufficient)

Troubleshooting​

Preferred Table Not Being Used​

Check:

  1. Confirm the table is saved as preferred (⭐ visible)
  2. Ensure the table has metadata descriptions (improves AI understanding)
  3. Check that the table is not hidden by an admin
  4. Re-run the query — the AI always receives preferred tables regardless of the question

Cannot Mark as Preferred​

"Table is hidden" — Admin has excluded this table; ask your admin to unhide it first.

"Limit reached" — You've reached the MAX_PREFERRED_TABLES limit. Remove some preferred tables first, or ask your admin to increase the limit.

"Access denied" — READONLY users cannot set preferences.

Preferred Tables Not Appearing in Sidebar​

The Query page loads preferred tables on page load. If you just added a new preferred table:

  1. Refresh the Query page
  2. The ⭐ star should now appear next to your preferred tables

Permissions​

ActionUSERADMINREADONLY
View own preferred tables✓✓✗
Mark tables as preferred✓✓✗
Remove preferred tables✓✓✗
Configure MAX_PREFERRED_TABLES limit✗✓ (via env)✗

Note: Preferred tables are per-user. Admins cannot view or modify other users' preferred tables.

Technical Details​

How the LLM Receives Preferred Tables​

The Nexus orchestration service fetches the user's preferred tables (with full metadata) before every SQL generation call. They are injected into the LLM prompt under a dedicated === USER'S PREFERRED TABLES (★ PRIORITIZE THESE ★) === section, appearing before the regular schema recommendations. This ensures the AI considers preferred tables first for every query.

Storage​

Preferred tables are stored in the user_schema_preferences table:

  • is_preferred (boolean) — marks the preference
  • columns_metadata (JSONB) — stores column names, types, descriptions
  • table_metadata (text) — table-level description
  • User-specific (not shared across users)
  • Audit timestamps (created_at, updated_at)

Metadata Fetching​

When you mark a table as preferred, the system automatically fetches its column definitions from the schema cache and any user-provided descriptions from the metadata store. This is done once at mark-time and stored — subsequent queries use the cached metadata without any extra lookups.

Additional Resources​