Data access control

AI agents offer flexible data access control to balance insights with privacy and security. By default, agents have data access enabled, and you can disable it per agent when you want metadata-only behavior.

Who can see what

Three controls decide what an agent can reach on behalf of the person asking, and they stack:

Layer	What it decides	Where it’s set
Agent tags	Which explores and fields the agent can see at all	Tags in your models and in the agent settings
User attributes	Which rows, columns and tables the asking user gets from those explores	`sql_filter`, `required_attributes` and `any_attributes` in your models
Raw SQL	Whether the asking user can run SQL outside the semantic layer, and which schemas it can read	The user’s `manage:SqlRunner` ability, the per-thread SQL mode toggle, and Agent data scope

The first two apply to every answer the agent builds from the semantic layer, which is its default mode. The third sits outside the semantic layer: raw SQL is not filtered by user attributes, and only users who could already open the SQL Runner can turn it on. Agent instructions shape how the agent reasons and answers; they can’t widen what it reaches. For a worked setup over explores that some users can only partly see, read Agent access to restricted data. The agent and its model never connect to your warehouse themselves. The model asks for a query through a tool, and Lightdash compiles and runs it over the project’s warehouse connection, the same query path Explore and the SQL Runner use. The model only sees the results Lightdash returns, and only when data access is enabled. On a project that requires personal warehouse credentials, that connection is the signed-in person’s own saved credentials — the same ones their charts and Explore queries use. See When are personal warehouse credentials used?. On Snowflake, BigQuery, Databricks, Athena, Postgres, Redshift, Trino and ClickHouse, agent identity also lets the warehouse decide what agent queries can read. With agent identity on, Lightdash also checks who can read each saved result. See Who can read a saved result.

Scoping raw SQL to specific schemas

Raw SQL bypasses the semantic layer, so tags and user attributes don’t narrow it. Agent data scope is the project setting that limits which warehouse schemas and catalogs raw SQL can read instead. Find it at Settings → Current project → Agent data scope, where the card is titled Warehouse access. The page only shows when AI agents are available for your organization. The setting has four lists:

Allowed schemas — raw SQL can only read from these. Empty means no restriction.
Allowed catalogs — optional, and only selectable once you’ve allowed at least one schema. Narrows the allowed schemas to specific catalogs or databases.
Excluded schemas and Excluded catalogs — never readable, even when the allow lists above would permit them. A denial always wins over an allow.

Agent data scope restricts raw SQL run by AI agents in SQL mode and by the MCP server’s Run SQL tool. The human SQL Runner is deliberately not scoped — the setting narrows what an agent can reach, not what a person with manage:SqlRunner can query.

The lists work at schema and catalog level only, with no table-level or name-prefix rule. If your staging, intermediate and mart models share one schema, Agent data scope can’t separate the marts from the rest. Build your mart models into their own schema and allow only that schema instead.

Agent data scope is a check Lightdash runs before sending the query to your warehouse, not a warehouse permission — restricting the warehouse credential’s own grants is the stronger control. Pair the setting with removing manage:SqlRunner from roles that shouldn’t run raw SQL at all, and treat agent instructions and agent context as guidance rather than enforcement — they shape how the agent reasons, not what it’s allowed to query.

Data access modes

Data access enabled (default):

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

Metadata-only mode:

Agents can see your data structure, field names, and model definitions
They can generate appropriate queries and visualizations
No actual data values are shared with the agent — its query tools return row counts (and column names, for SQL queries) but never the rows themselves
Perfect for exploring data structure and creating initial analyses

In metadata-only mode the agent is told to describe what each chart shows (fields, filters and sorts) and never to state figures. That is guidance to the model, not a check on its reply, so an answer can still include a number the agent never saw. The charts show real results, because Lightdash runs their queries itself, so trust the chart over any figure in the text. If an agent keeps writing numbers, repeat the rule in its instructions, or turn data access on so the text comes from real results. Content editing requires data access. If you turn data access off, content editing is automatically turned off and locked until you re-enable data access. To change data access, go to your agent settings and toggle Data Access. Turn it off when you want the agent to work only with your data model structure and not see actual data values.

Personalizing answers to who is asking

By default, an agent doesn’t know who it’s talking to — everyone gets the same style of answer. When you turn on Pass user information, the agent tailors its responses to the person asking, so a business user and a data developer can get differently-pitched answers to the same question. With this setting on, a non-technical viewer gets plain-language answers and is pointed to the data team when something needs changing, while a technical user gets more detailed, hands-on guidance. The agent stays the same — only the tone and level of detail adapt to the audience. What the agent receives when enabled:

The user’s name
Their role
Their group memberships

To turn it on, open your agent settings, go to the Data Access section, and enable Pass user information. It’s off by default, so answers stay uniform until you opt in.

Pass user information toggle in AI agent Data Access settings

This only applies when the agent knows who is asking. In the Lightdash app that’s always the logged-in user. On Slack, you need to enable the AI Agents OAuth requirement so each Slack user is identified individually — otherwise user information is left out and answers stay generic.

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:

dbt tags - Native dbt tags applied at the model level (using the tags property or config.tags). These control explore-level access
Lightdash metadata tags - Tags defined in the Lightdash meta section, applied at the column level (individual metrics and dimensions). These control field-level access

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

Interactive preview of explores and fields filtered by tags in agent settings — Preview available explores and fields as you add tags

Two levels of tagging:

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

Watch this demo to see tag-based access control in action:

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

Virtual views never carry explore-level or field-level tags, so they can never match any configured tag. As soon as you add any tag to an agent, every virtual view is excluded from that agent regardless of what the tag is — a virtual view is only reachable by an agent with no tag restriction configured.

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

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
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

Joined tables: Tagging the base model does not restrict joined models. Once an explore is visible, each joined table is filtered by its own tags only. A joined table with no tags falls into explore-level mode, so all of its fields are visible to the agent. To restrict a joined model’s fields, add field-level tags to that model (see Scenarios 4 and 6 below).

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

models:
  - name: marketing_campaigns
    config:
      tags: ["marketing", "ai"] #    <--------- dbt native tags (explore-level)
    columns:
      - name: campaign_name
        config:
          meta:
            dimension:
              type: string
      - name: impressions
        config:
          meta:
            metrics:
              total_impressions:
                type: sum

models:
  - name: marketing_campaigns
    tags: ["marketing", "ai"] #    <--------- dbt native tags (explore-level)
    columns:
      - name: campaign_name
        meta:
          dimension:
            type: string
      - name: impressions
        meta:
          metrics:
            total_impressions:
              type: sum

Adding tags to individual metrics & dimensions

For more granular control, tag specific metrics and dimensions:

View code examples

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

models:
  - name: orders
    columns:
      - name: status
        meta:
          dimension:
            tags: ['ai', 'sales'] #    <--------- tagging the dimension
      - name: location
        meta:
          dimension:
            tags: ['ai', 'operations'] #    <--------- tagging the dimension
      - name: amount
        description: Total amount of the order
        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:
      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:
      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

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

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

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

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

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

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.

Scenario 6: Tagged base model with an untagged joined model

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

models:
  - name: customers
    columns:
      - name: customer_id # no tags
      - name: email # no tags
      - name: phone # no tags

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

orders table: ALL fields visible (explore-level mode - explore tags match)
customers table: ALL fields visible (explore-level mode - the joined model has no tags anywhere, so nothing restricts it)

Tagging the base model does not restrict joined models. A tagged base model exposes every field of an untagged joined model to the agent. To restrict a joined model’s fields, add field-level tags to that model, as in Scenario 4.

User attributes and permissions

When an agent answers from the semantic layer, which is its default mode, it respects 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. The exception is raw SQL, covered below.

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
Agents respect required_attributes on metrics. Metrics defined under restricted columns inherit the column’s restriction unless they set their own; model-level metrics are not restricted by the columns they reference (see metric access control)
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: By default, AI agents use the attributes of the user who created the agent. To have each Slack user’s individual permissions respected, enable the AI Agents OAuth requirement toggle in your Lightdash Slack settings. When enabled, each Slack user must OAuth into Lightdash before using the agent, and their individual permissions are applied to all queries.

How this works behind the scenes

When an agent generates a query:

The agent receives the user’s complete attribute profile (both direct user attributes and group attributes)
All sql_filter rules are automatically applied to the generated SQL
Dimensions and tables with required_attributes are filtered from the available schema
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: Semantic queries the agent generates cannot bypass user attribute restrictions
Error handling: If an agent attempts to access restricted data through the semantic layer, the query fails with a permissions error

Raw SQL is outside the semantic layer

User attributes are enforced by the semantic layer, so they apply to every query built from an explore: Explore, charts and dashboards, and AI agents answering in their default (semantic) mode. Anything that runs raw SQL against the warehouse runs outside the semantic layer, and sql_filter, required_attributes and any_attributes do not apply to it:

The SQL Runner
SQL mode in an AI agent conversation
The Run SQL tool of the Lightdash MCP server
Hand-written SQL inside a semantic query: custom SQL dimensions, custom SQL metrics, and SQL table calculations. They’re pasted into the query as written, which is why authoring them needs manage:CustomFields or manage:CustomSqlTableCalculations.

Every surface on this list needs a permission that Developer and Admin roles hold by default: manage:SqlRunner for the first three, manage:CustomFields or manage:CustomSqlTableCalculations for the last. A user without those cannot run raw SQL from any of them, whatever an agent’s instructions say. If someone needs raw SQL and warehouse-enforced permissions at the same time, require personal warehouse credentials on the project so their queries run as their own warehouse user, and put the restrictions in the warehouse.

Limiting how much agent queries scan

On BigQuery, you can set an AI agent query limit on the connection. Lightdash dry-runs every agent query before it executes and refuses queries estimated to process more than the limit. The agent receives the estimate so it can narrow the query and try again. Maximum bytes billed, or AI agent maximum bytes billed when it’s set, stays the hard limit, because dry-run estimates can be lower than what a query is billed for. See Query cost estimates in the BigQuery connection settings.

​Who can see what

​Scoping raw SQL to specific schemas

​Data access modes

​Personalizing answers to who is asking

​Limiting access to specific explores and fields

​How filtering works

​Adding tags at the model level

​Adding tags to individual metrics & dimensions

​Common scenarios

​User attributes and permissions

​How user attributes flow through AI queries

​Default behavior

​How this works behind the scenes

​Example: Regional sales access

​Security considerations

​Raw SQL is outside the semantic layer

​Limiting how much agent queries scan

Who can see what

Scoping raw SQL to specific schemas

Data access modes

Personalizing answers to who is asking

Limiting access to specific explores and fields

How filtering works

Adding tags at the model level

Adding tags to individual metrics & dimensions

Common scenarios

User attributes and permissions

How user attributes flow through AI queries

Default behavior

How this works behind the scenes

Example: Regional sales access

Security considerations

Raw SQL is outside the semantic layer

Limiting how much agent queries scan