> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.cloudquant.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fine-Grained Permissions

> Restrict user query scope with trial periods, date ranges, row limits, keys, and column filters

# Fine-grained permissions

Fine-grained permissions let Super Admins apply additional restrictions on top of standard dataset entitlements. Use them to enforce trial periods, limit historical lookback, cap query volume, or restrict which keys and columns a user can access.

Fine-grained rules apply **per dataset** or **per dataset group** and are configured from the user's **Data Permissions** dialog.

## When to use fine-grained permissions

| Scenario                            | Recommended restriction                 |
| ----------------------------------- | --------------------------------------- |
| Time-limited trial                  | **Trial Range**                         |
| Historical data only (no live feed) | **Data Query Range** → Historical Only  |
| Rolling window (e.g., last 90 days) | **Data Query Range** → Rolling Window   |
| Fixed evaluation period             | **Data Query Range** → Fixed Date Range |
| Cap download size                   | **Max Rows**                            |
| Limit API usage                     | **Max Queries**                         |
| Restrict to a symbol universe       | **Keys**                                |
| Hide sensitive columns              | **Columns**                             |

<Note>
  Fine-grained permissions require an underlying dataset or group entitlement. They cannot grant access on their own — the user must already be entitled to the dataset or group.
</Note>

## Opening fine-grained settings

<Steps>
  <Step title="Open Data Permissions">
    From the Users page, click the data-permissions icon for the target user.
  </Step>

  <Step title="Select the dataset or group">
    Ensure the dataset or dataset group row is checked in the permissions table.
  </Step>

  <Step title="Open fine-grained settings">
    Click the gear icon (**Actions** column) on the selected row. The icon appears filled (blue) when fine-grained rules already exist for that item.
  </Step>

  <Step title="Configure and save">
    Enable the restriction sections you need, set values, click **Done** to return to the permissions table, then **Save Changes**.
  </Step>
</Steps>

<Warning>
  Fine-grained settings are not saved until you click **Save Changes** on the main Data Permissions dialog. Clicking **Done** only returns you to the entitlement table.
</Warning>

## Restriction sections

Each section is controlled by an **Enable** toggle. Disabled sections are ignored — their fields are not sent to the backend.

### Trial Range

Limits when the user can access the platform for a specific dataset or group, independent of the data date range.

| Field            | Description                              |
| ---------------- | ---------------------------------------- |
| **Trial Period** | Start and end dates for the trial window |

Outside the trial window, queries against the restricted dataset or group are denied even if other entitlements exist.

### Data Query Range

Controls what type of data the user can query and over what time horizon.

| Type                       | Behavior                                                                         |
| -------------------------- | -------------------------------------------------------------------------------- |
| **Historical Only**        | Live/real-time data is blocked; only historical queries are allowed              |
| **Live Only**              | Only live/real-time data is accessible                                           |
| **Both Historical & Live** | No restriction on query mode                                                     |
| **Fixed Date Range**       | Queries are limited to a specific start/end date range                           |
| **Rolling Window**         | Queries are limited to the last N days from the current date (**Days Lookback**) |

### Limits and Settings

Caps query scope and restricts the symbol universe and visible columns.

| Field           | Description                                                                                        |
| --------------- | -------------------------------------------------------------------------------------------------- |
| **Max Rows**    | Maximum number of rows returned per query                                                          |
| **Max Queries** | Maximum number of queries allowed (usage cap)                                                      |
| **Max Keys**    | Maximum number of keys (symbols) that can be queried in a single request                           |
| **Keys**        | Allow-list of specific keys. Enter individually or paste comma-separated values                    |
| **Columns**     | Allow-list of column names from the dataset schema. Search and multi-select from available columns |

<Tip>
  System columns (`_seq`, `timestamp`, `muts`, `symbol`) are excluded from the column picker because they are always required for query execution.
</Tip>

## Dataset vs group rules

Fine-grained permissions can target either:

* **A single dataset** — restrictions apply only to that dataset
* **A dataset group** — restrictions apply to the group entitlement as a whole

Group-level rules are configured the same way: select the group row, click the gear icon, and set restrictions. The dialog title shows the group name.

## Removing fine-grained permissions

To remove all restrictions for a dataset or group:

1. Open the fine-grained settings (gear icon).
2. Disable all three sections (**Trial Range**, **Data Query Range**, **Limits and Settings**), or clear all restriction values.
3. Click **Done**, then **Save Changes**.

Alternatively, revoke the entire dataset or group entitlement — removing an entitlement automatically removes its associated fine-grained rules.

## Interaction with connection entitlements

Datasets inherited from a **connection-level** entitlement cannot have individual fine-grained rules configured in the per-user permissions UI. The gear icon is hidden for locked (inherited) datasets.

To apply fine-grained restrictions in this case, either:

* Assign a direct dataset entitlement instead of (or in addition to) the connection entitlement, or
* Manage access at the connection level through connection permission settings

## How restrictions are enforced

When a user submits a query, the entitlements service evaluates:

1. Whether the user has a dataset, group, or connection entitlement
2. Whether any fine-grained rules apply to that dataset
3. Whether the query parameters (date range, keys, columns, row count) fall within the allowed bounds

If a query violates a restriction, it is rejected before data is returned.

## Example configurations

### 90-day rolling trial

1. Enable **Trial Range** and set the trial period dates.
2. Enable **Data Query Range**, select **Rolling Window**, set **Days Lookback** to `90`.
3. Save.

### Symbol-restricted research access

1. Enable **Limits and Settings**.
2. Set **Keys** to the allowed symbol list (e.g., `AAPL`, `MSFT`, `GOOG`).
3. Optionally set **Max Rows** to cap result size.
4. Save.

### Column-redacted dataset

1. Enable **Limits and Settings**.
2. Use **Columns** to select only the fields the user should see.
3. Save.

## Checking effective access

Users can verify entitled datasets from Python:

```python theme={null}
liberator.datasets(entitled=True)
```

Fine-grained restrictions are enforced at query time and are not visible in the dataset list. If a query fails due to a restriction, the error message indicates which limit was exceeded.

For admin-side verification, open the user's **View** dialog or the **JSON** tab (Super Admin) to inspect the full permissions payload including `fine_grain_permissions`.