> ## Documentation Index
> Fetch the complete documentation index at: https://docs.farmtrace.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters and role access

> Apply source filters and calculate role-specific visibility and downloaded columns.

# Filters and role access

## `queryFilter`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "queryFilter": "[Active] = true"
}
```

`queryFilter` is an optional source-data filter applied when the table is downloaded.

The expression must use the source database's supported filtering syntax.

Use the exact source field names.

### No filter

If the table does not require a filter:

* omit `queryFilter`; or
* set it to `null`.

For example:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "queryFilter": null
}
```

### Troubleshooting filters

Test a filter against the source database before publishing it.

An incorrect filter can make a correctly configured table appear empty.

When diagnosing an empty table, avoid changing both the filter and the column configuration at the same time. Isolating one change at a time makes the source of the problem easier to identify.

***

## `roleAccess`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "roleAccess": [
    {
      "role": "Field Operators",
      "isAllowedToView": true,
      "addedColumns": [],
      "hideColumns": []
    }
  ]
}
```

`roleAccess` is an optional list of role-specific configuration rules.

A role rule can affect:

* whether the table appears in the table list; and
* which columns are downloaded for that role.

Each role rule supports:

| Field             | Purpose                                                             |
| ----------------- | ------------------------------------------------------------------- |
| `role`            | Exact user-role name. Matching is case-sensitive.                   |
| `isAllowedToView` | Overrides table visibility for the matching role.                   |
| `addedColumns`    | Additional fields downloaded for the matching role.                 |
| `hideColumns`     | Fields removed from the requested column set for the matching role. |

Use only **one rule per role**.

There is no:

* wildcard matching;
* partial role matching;
* case-insensitive matching;
* closest-role matching.

***

## How role-based columns are calculated

For a user with a matching role rule, the app effectively performs:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
effectiveColumns =
    requestColumns
    + addedColumns
    - hideColumns
```

The order of operations is:

1. start with `requestColumns`;
2. add the matching role's `addedColumns`;
3. remove the matching role's `hideColumns`.

***

## Example

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "requestColumns": [
    "@row.id",
    "Name",
    "Email",
    "Phone"
  ],
  "roleAccess": [
    {
      "role": "Field Operators",
      "isAllowedToView": true,
      "addedColumns": [],
      "hideColumns": [
        "Email"
      ]
    }
  ]
}
```

For `Field Operators`, the effective downloaded columns are:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
@row.id
Name
Phone
```

`Email` is removed by the role rule.

***

## Important distinction: downloaded vs displayed fields

`hideColumns` removes a field from the data downloaded for that role.

It is **not** merely a visual table-screen setting.

Do not add a field to `hideColumns` if that field is required by:

* a dropdown;
* a scan;
* a lookup;
* a report;
* a dependent filter;
* a posting action;
* another component using that table.

A field can be required internally even when users do not need to see it directly on the table screen.

***

## How role-based visibility works

For a user whose role matches a `roleAccess` rule:

| `isAllowedToView` | Behaviour                                              |
| ----------------- | ------------------------------------------------------ |
| `true`            | Table is shown, even when global `visible` is `false`. |
| `false`           | Table is hidden, even when global `visible` is `true`. |
| `null`            | Falls back to global `visible`.                        |

If the user's role does not match any rule, the global `visible` configuration is used.

If the role value is empty or does not match exactly, no role-specific rule is applied.

***