> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/embed/permissions-and-row-level-security/dataset-level-vs-row-level-security.md).

# Dataset-Level VS Row-Level Security

{% hint style="info" %}
**Target Audience**: Non technical users & Developers
{% endhint %}

### TL;DR

Toucan AI utilizes dataset-level security to restrict access to entire data sources and Row-Level Security (RLS) to filter specific records within a shared dataset.

***

### When to use this

Use this page to determine the appropriate security layer for isolating data between different departments, teams, or external tenants.

***

### Dataset-level security

Dataset-level security defines which users or roles are authorized to access a specific data source in its entirety.

* **Definition**: This layer restricts access to the complete dataset; users without permission cannot query or visualize any part of the source.
* **How it works**: Permissions are assigned at the dataset object level. Unauthorized users are unable to view the dataset within the Toucan AI interface.
* **Use case**: Separating sensitive data by department, such as ensuring HR datasets remain private from the general Sales team.
* **Example**: A "Finance" dataset is configured so it is only visible to the Finance group; no other users can interact with its metadata or values.

***

### Row-Level Security (RLS)

RLS provides a granular filtering mechanism that allows multiple users to access the same dataset while only viewing records relevant to them.

* **Definition**: This layer filters data rows within a dataset based on dynamic user attributes.
* **How it works**: Toucan AI injects filtering policies into the query at execution time, utilizing attributes passed in the authentication token.
* **Use case**: Multi-tenant environments where all sales representatives use a single "Global Sales" dashboard but are restricted to their specific regional data.
* **Example**: In a "Customer Orders" dataset, an employee with the attribute `region: France` only sees French orders, while a manager with broader attributes may see all regions.

***

### Comparison and selection

| Feature          | Dataset-Level Security                    | Row-level Security (RLS)                                      |
| ---------------- | ----------------------------------------- | ------------------------------------------------------------- |
| **Scope**        | Entire dataset or data source.            | Individual rows within a dataset.                             |
| **Visibility**   | Dataset is hidden if unauthorized.        | Dataset is visible, but content is filtered.                  |
| **Management**   | Assigned to specific roles or teams.      | Driven by dynamic user attributes (e.g., `department`, `ID`). |
| **Primary Goal** | Strict boundaries between business units. | Personalized, multi-tenant data isolation.                    |

***

### Implementation best practices

* **Layered Security**: Start with dataset-level restrictions for broad access control, then apply RLS for fine-grained filtering.
* **Single Source of Truth**: Use RLS to avoid duplicating datasets or dashboards for different user groups.
* **Validation**: Test security policies with various user attribute combinations to ensure compliance and correct data isolation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toucanai.cloud/embed/permissions-and-row-level-security/dataset-level-vs-row-level-security.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.