Data access control

Understand how AI agents access and use your data

AI agents offer flexible data access control to balance insights with privacy and security. By default, agents work with metadata only, but you can optionally enable data access for deeper analysis.

Data access modes

Metadata-only mode (default):

• Agents can see your data structure, field names, and model definitions
• They can generate appropriate queries and visualizations
• No actual data values (except for one-row query results) are shared with the agent
• Perfect for exploring data structure and creating initial analyses

Data access enabled:

• Agents receive actual query results in addition to metadata
• Can provide specific insights, identify trends, and analyze patterns in your data
• Offers detailed summaries and data-driven recommendations
• Can search for actual field values to ensure accurate filters when building visualizations
• Only shares data when explicitly enabled per agent

Data access is optional and controlled per agent. When disabled, agents only work with your data model structure and cannot see actual data values. This ensures sensitive information is only shared when you explicitly choose to enable this capability.

To enable data access, go to your agent settings and toggle the “Data Access” option.

Limiting access to specific explores and fields

You can control which explores and fields your AI agent can access using tags. When you configure tags in your agent settings, the agent will only see explores and fields that have matching tags.

Two tagging options:

• Lightdash metadata tags - Tags defined in the Lightdash meta section, which can be applied at both the table level (model) and column level (individual metrics and dimensions)
• dbt tags - Native dbt tags applied at the table level

How tag matching works:

• Add one or more tags to your agent settings
• Fields or explores with any of those tags will be accessible to the agent
• If no tags are configured, the agent can access everything
• As you add tags, you can interactively explore which explores and fields will be available in the agent settings interface

Preview available explores and fields as you add tags

Two levels of tagging:

1. Explore-level tags - Tag the model to control access to entire explores
2. Field-level tags - Tag individual metrics and dimensions for granular control

How filtering works

The filtering behavior depends on how you’ve tagged your models:

Explore visibility:

• An explore is only visible if its base table has matching tags at either:
  • Explore level (model tags match agent tags), OR
  • Field level (at least one base table field has matching tags)
• If only joined tables have matching tags but the base table doesn’t, the explore will be hidden

Field visibility per table:

Each table in an explore is filtered independently using one of two modes:

1. Field-level mode (when ANY field in the table has tags defined):

   • Only fields with matching tags are visible
   • Other fields are hidden, even if the explore is tagged
   • Note: An empty tags array (tags: []) activates field-level mode but matches nothing

2. Explore-level mode (when NO fields in the table have tags):

   • If explore tags match: ALL fields in the table are visible
   • If explore tags don’t match: NO fields are visible

Adding tags at the model level

Tag entire models to give your AI agent access to all metrics and dimensions within that explore:

View code examples

dbt 1.10+

models:
  - name: marketing_campaigns
    config:
      meta:
        tags: ["marketing", "ai"] #    <--------- tagging the entire model
    columns:
      - name: campaign_name
        config:
          meta:
            dimension:
              type: string
      - name: impressions
        config:
          meta:
            metrics:
              total_impressions:
                type: sum

Adding tags to individual metrics & dimensions

For more granular control, tag specific metrics and dimensions:

View code examples

dbt 1.10+

models:
  - name: orders
    columns:
      - name: status
        config:
          meta:
            dimension:
              tags: ["ai", "sales"] # <--------- tagging the dimension
      - name: location
        config:
          meta:
            dimension:
              tags: ["ai", "operations"] # <--------- tagging the dimension
      - name: amount
        description: Total amount of the order
        config:
          meta:
            metrics:
              total_order_amount:
                type: sum
                format: usd
                round: 2
                tags: ["ai", "finance"] # <--------- tagging the metric

Common scenarios

Here are some common tagging scenarios and their results:

Scenario 1: Explore-level only (no field tags)

models:
  - name: customers
    config:
      meta:
        tags: ["ai-enabled"]
    columns:
      - name: customer_name
      - name: email

Result: If agent has ["ai-enabled"] tag, ALL fields in the customers explore are visible.

Scenario 2: Field-level only (no explore tags)

models:
  - name: customers
    columns:
      - name: customer_name
        config:
          meta:
            dimension:
              tags: ["ai-enabled"]
      - name: email
        config:
          meta:
            dimension:
              tags: ["pii"]

Result: If agent has ["ai-enabled"] tag, only customer_name is visible. The email field is hidden.

Scenario 3: Mixed - explore tagged with fields that have different tags

models:
  - name: orders
    config:
      meta:
        tags: ["ai-enabled"]
    columns:
      - name: order_id
        config:
          meta:
            dimension:
              tags: ["pii"]
      - name: status
        config:
          meta:
            dimension:
              tags: ["internal"]

Result: If agent has ["ai-enabled"] tag, NO fields are visible. Field-level mode is active (because fields have tags), and none of the field tags match “ai-enabled”.

Scenario 4: Mixed mode - base model with explore tags, joined model with field tags

orders.yml (base model)

models:
  - name: orders
    config:
      meta:
        tags: ["ai-enabled"]
        joins:
          - join: customers
            sql_on: ${customers.customer_id} = ${orders.customer_id}
    columns:
      - name: order_id
      - name: status
      - name: customer_id

Result: If agent has ["ai-enabled"] tag:

• orders table: ALL fields visible (explore-level mode - no field tags defined)
• customers table: Only email visible (field-level mode - has field tags, only email matches)

Scenario 5: Only joined table has matching tags

orders.yml (base model)

models:
  - name: orders
    config:
      meta:
        joins:
          - join: customers
            sql_on: ${customers.customer_id} = ${orders.customer_id}
    columns:
      - name: order_id # no tags
      - name: status # no tags

Result: The entire explore is HIDDEN because the base table (orders) has no matching tags.

An explore is only visible if the base table has matching tags (either at explore level or field level). Having matching tags only in joined tables is not enough.

User attributes and permissions

AI agents automatically respect all data access controls configured through user attributes. This ensures that agents only access data that the user is authorized to see, maintaining your existing security policies.

How user attributes flow through AI queries

When an AI agent generates and executes queries on behalf of a user, it inherits that user’s attribute values and applies them to all data access:

Row-level security:

• Agents automatically apply sql_filter rules defined in your models
• Only rows matching the user’s attribute values are included in query results
• Example: If a user has sales_region: 'EMEA', the agent will only query data for that region

Column-level security:

• Agents respect required_attributes on dimensions
• Columns the user cannot access are invisible to the agent
• Metrics derived from restricted columns are also unavailable
• Example: If salary requires is_admin: 'true', non-admin users’ agents cannot query salary data

Table-level security:

• Agents respect required_attributes on models
• Tables the user cannot access are completely hidden from the agent
• The agent cannot reference or join restricted tables
• Example: If payments requires is_admin: 'true', non-admin users’ agents cannot query the payments table

Default behavior

In the Lightdash app: AI agents automatically use the logged-in user’s attributes for all queries.

In Slack: AI agents currently use the attributes of the user who created the agent. We plan to respect user attributes based on Slack user email in the future—reach out if you need this feature!

How this works behind the scenes

When an agent generates a query:

1. The agent receives the user’s complete attribute profile (both direct user attributes and group attributes)
2. All sql_filter rules are automatically applied to the generated SQL
3. Dimensions and tables with required_attributes are filtered from the available schema
4. The agent only sees and can query data within the user’s permissions

This happens transparently—the agent doesn’t need special configuration. Your existing user attribute rules automatically protect AI-generated queries just like they protect manual queries.

Example: Regional sales access

Consider this model configuration:

models:
  - name: sales
    meta:
      sql_filter: ${TABLE}.region IN (${lightdash.attributes.sales_region})
    columns:
      - name: revenue
      - name: customer_name
        meta:
          dimension:
            required_attributes:
              can_view_pii: "true"

For a user with sales_region: 'EMEA' and no can_view_pii attribute:

• The agent can query revenue data, but only for EMEA region
• The agent cannot see or query customer_name (PII restriction)
• If the agent tries to analyze customer names, it will fail with a permissions error
• All generated queries automatically include WHERE region IN ('EMEA')

Security considerations

• Metadata mode: Even in metadata-only mode, agents respect user attributes when showing available fields
• Data access mode: When data access is enabled, query results are filtered by user attributes
• Query generation: Agents cannot generate queries that bypass user attribute restrictions
• Error handling: If an agent attempts to access restricted data, the query fails with a permissions error

Custom SQL in table calculations or SQL Runner can potentially bypass user attribute filters. AI agents use the standard query interface and cannot bypass these restrictions.