# Managing data filters
To implement column-level, row-level, and cell-level security, you can create and maintain data filters. Each data filter belongs to a Data Catalog table. You can create multiple data filters for a table, and then use one or more of them when granting permissions on the table. You can also define and apply data filters on nested columns that have `struct` datatypes allowing users to access only sub-structures of nested columns.
You require `SELECT` permission with the grant option to create or view a data filter. To allow principals in your account to view and use a data filter, you can grant the `DESCRIBE` permission on it.
**Note**
Lake Formation doesn't support granting `Describe` permission on a data filter, which is shared from another account.
You can manage data filters by using the AWS Lake Formation console, the API, or the AWS Command Line Interface (AWS CLI).
For information about data filters, see [Data filters in Lake Formation](data-filtering.md#data-filters-about)
# Creating a data filter
You can create one or more data filters for each Data Catalog table.
**To create a data filter for a Data Catalog table (console)**
1. Open the Lake Formation console at [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/).
Sign as a data lake administrator, the target table owner, or a principal who has a Lake Formation permission on the target table.
1. In the navigation pane, under **Data catalog**, choose **Data filters**.
1. On the **Data filters** page, choose **Create new filter**.
1. In the **Create data filter** dialog box, enter the following information:
+ Data filter name
+ Target database – Specify the database that contains the table.
+ Target table
+ Column-level access – Leave this set to **Access to all columns** to specify row filtering only. Choose **Include columns** or **Exclude columns** to specify column or cell filtering, and then specify the columns to include or exclude.
Nested columns – If you're applying the filter on a table that contains nested columns, you can explicitly specify sub-structures of the nested struct columns within a data filter.
When you grant SELECT permission to a principal on this filer, the principal executing the following query, will only see the data for `customer.customerName` and not `customer.customerId`.
```
SELECT "customer" FROM "example_db"."example_table";
```
![\[Column-level access settings with options to include specific columns and filter rows.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/nested-column-filter.png)
When you grant permissions to the `customer` column, the principal receives the access to the column and the nested fields under the column (`customerName` and `customerID`).
+ Row filter expression – Enter a filter expression to specify row or cell filtering. For supported data types and operators, see [PartiQL support in row filter expressions](partiql-support.md). Choose **Access to all rows** to grant access to all .
You can include partial column structs from nested columns in a row filter expression to filter rows that contain specific value.
When a principal is granted permissions to a table with a row filter expression `Select * from example_nestedtable where customer.customerName <>'John'`, and **Column-level** access is set to **Access to all columns**, the query results shows only rows where `customerName <>'John'` evaluates to true.
The following screenshot shows a data filter that implements cell filtering. In queries against the `orders` table, it denies access to the `customer_name` column and shows only rows that have 'pharma' in the `product_type` column.
![\[The data filter window contains these fields, arranged vertically: Data filter name; Target database; Target table; Option button group with the options Access to all columns, Include columns, and Exclude columns; Select columns (drop-down list); Row filter expression (multi-line text box). The Exclude columns option is selected, the customer_name column is selected for exclusion, and the Row filter expression field contains 'product_type='pharma'.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/data-filter-sample-pharma.png)
1. Choose **Create filter**.
**To create a data filter with cell-filter policies on a nested field**
This section uses the following sample schema to show how to create a data cells filter:
```
[
{ name: "customer", type: "struct" },
{ name: "customerApplication", type: "struct" },
{ name: "product", type: "struct,type:string>" },
{ name: "purchaseId", type: "string" },
]
```
1. On the **Create a data filter**, page enter a name for the data filter.
1. Next, use the drop-down to choose a database name and table name.
1. In the **Column-level access** section, choose Included columns, and select a nested column (`customer.customerName`).
1. In the **Row-level access** section, choose the **Access to all rows** option.
1. Choose **Create filter**.
When you grant `SELECT` permission on this filter, the principal gets access to all rows in the `customerName` column.
1. Next, define another data filter for the same database/table.
1. In the **Column-level access** section, choose Included columns, and select another nested column (`customer.customerid`).
1. In the **Row-level access** section, choose **Filter rows**, and enter a **Row filter expression** (`customer.customerid <> 5`).
1. Choose **Create filter**.
When you grant `SELECT` permission on this filter, the principal receives access to all rows in the `customerName`, and `customerId` fields except the cell where the value is 5 in the `customerId` column.
# Granting data filter permissions
You can grant the `SELECT`, `DESCRIBE` and `DROP` Lake Formation permissions on data filters to principals.
At first, only you can view the data filters that you create for a table. To enable another principal to view a data filter and grant Data Catalog permissions with the data filter, you must either:
+ Grant `SELECT` on a table to the principal with the grant option, and apply the data filter to the grant.
+ Grant the `DESCRIBE` or `DROP` permission on the data filter to the principal.
You can grant the `SELECT` permission to an external AWS account. A data lake administrator in that account can then grant that permission to other principals in the account. When granting to an external account, you must include the grant option so that administrator of the external account can further cascade the permission to other users in his/her account. When granting to a principal in your account, granting with the grant option is optional.
You can grant and revoke permissions on data filters by using the AWS Lake Formation console, the API, or the AWS Command Line Interface (AWS CLI).
------
#### [ Console ]
1. Sign in to the AWS Management Console and open the Lake Formation console at [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/).
1. In the navigation pane, under **Permissions**, choose **Data lake permissions**.
1. On the **Permissions** page, in the **Data permissions** section, choose **Grant**.
1. On the **Grant data permissions** page, choose the principals to grant the permissions to.
1. In the LF-Tags or catalog resources section, choose **Named data catalog resources**. Then choose the database, table, and data filter for which you want to grant permissions.
![\[\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/grant-data-filter-perms-step2.png)
1. In the **Data filter permissions** section, choose the permissions you want to grant to the selected principals.
![\[\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/grant-perms-on-filters.png)
------
#### [ AWS CLI ]
+ Enter a `grant-permissions` command. Specify `DataCellsFilter` for the `resource` argument, and specify `DESCRIBE` or `DROP` for the `Permissions` argument and, optionally, for the `PermissionsWithGrantOption` argument.
The following example grants `DESCRIBE` with the grant option to user `datalake_user1` on the data filter `restrict-pharma`, which belongs to the `orders` table in the `sales` database in AWS account 1111-2222-3333.
```
aws lakeformation grant-permissions --cli-input-json file://grant-params.json
```
The following are the contents of file `grant-params.json`.
```
{
"Principal": {"DataLakePrincipalIdentifier": "arn:aws:iam::111122223333:user/datalake_user1"},
"Resource": {
"DataCellsFilter": {
"TableCatalogId": "111122223333",
"DatabaseName": "sales",
"TableName": "orders",
"Name": "restrict-pharma"
}
},
"Permissions": ["DESCRIBE"],
"PermissionsWithGrantOption": ["DESCRIBE"]
}
```
------
# Granting data permissions provided by data filters
Data filters represent a subset of data within a table. To provide data access to principals, `SELECT` permissions need to be granted to those principals. With this permission the principals can:
+ View the actual table name in list of tables shared with their account.
+ Create data filters on the shared table and grant permissions to their users on those data filters.
------
#### [ Console ]
**To grant SELECT permissions**
1. Go to the **Permissions** page in the Lake Formation console, and then choose **Grant**.
![\[\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/permissions-grant-action.png)
1. Select the principals you want to provide access to, and select **Named data catalog resources**.
![\[\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/grant-data-filter-perms-step2.png)
1. To provide access to the data that the filter represents, choose **Select** under **Data filter permissions**.
![\[\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/grant-data-filter-perms-step3.png)
------
#### [ CLI ]
Enter a `grant-permissions` command. Specify `DataCellsFilter` for the resource argument, and specify `SELECT` for the Permissions argument.
The following example grants `SELECT` with the grant option to user `datalake_user1` on the data filter `restrict-pharma`, which belongs to the `orders` table in the `sales` database in AWS account `1111-2222-3333`.
```
aws lakeformation grant-permissions --cli-input-json file://grant-params.json
```
The following are the contents of file `grant-params.json`.
```
{
"Principal": {
"DataLakePrincipalIdentifier": "arn:aws:iam::111122223333:user/datalake_user1"
},
"Resource": {
"DataCellsFilter": {
"TableCatalogId": "111122223333",
"DatabaseName": "sales",
"TableName": "orders",
"Name": "restrict-pharma"
}
},
"Permissions": ["SELECT"]
}
```
------
# Viewing data filters
You can use the Lake Formation console, AWS CLI, or the Lake Formation API to view data filters.
To view data filters, you must be a Data Lake administrator or have the required permissions on the data filters.
------
#### [ Console ]
1. Sign in to the AWS Management Console and open the Lake Formation console at [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/).
1. In the navigation pane, under **Data catalog**, choose **Data filters**.
The page displays the data filters you have access to.
![\[The Data filters page displays the available data filters with the following columns: Filter name, Table, Database, and Table catalog ID. The screenshot shows a single data filter with the following values: test-df, cloudtrailtest_cloudtrail, lakeformation_cloudtrail, redacted account ID. Above the table there are four buttons (from left to right): Refresh/reload, View (grayed out), Delete (grayed out), and "Create new filter". There is also a search field, which is empty.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/list-data-filters.jpg)
1. To view the data filter details, choose the data filter, and then choose View. A new window appears with the data filter detailed information.
![\[The "View data filter" window shows additional information about the selected data filter. The information displayed includes the name, database, table, column-level access setting, row filter expression, and the columns.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/list-data-filters-details.jpg)
------
#### [ AWS CLI ]
Enter a `list-data-cells-filter` command and specify a table resource.
The following example lists the data filters for the `cloudtrailtest_cloudtrail` table.
```
aws lakeformation list-data-cells-filter --table '{ "CatalogId":"123456789012",
"DatabaseName":"lakeformation_cloudtrail", "Name":"cloudtrailtest_cloudtrail"}'
```
------
#### [ API/SDK ]
Use the `ListDataCellsFilter` API and specify a table resource.
The following example uses Python to list the first 20 data filters for the `myTable` table.
```
response = client.list_data_cells_filter(
Table = {
'CatalogId': '111122223333',
'DatabaseName': 'mydb',
'Name': 'myTable'
},
MaxResults=20
)
```
------
# Listing data filter permissions
You can use the Lake Formation console to view the permissions granted on data filters.
To view permissions on a data filter, you must be a Data Lake administrator or have the required permissions on the data filter.
------
#### [ Console ]
1. Sign in to the AWS Management Console and open the Lake Formation console at [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/).
1. In the navigation pane, under **Permissions**, choose **Data permissions**.
1. On the **Data Permissions** page, click or tap in the search field, and on the **Properties** menu, choose **Resource type**.
1. On the **Resource type** menu, choose **Resource type: Data cell filter**.
The data filters that you have permissions on are listed. You might have to scroll horizontally to see the **Permissions** and **Grantable** columns.
![\[The Data Permissions page displays a table of permissions with the following columns: Principal, Resource type, Database, Table, Resource, Catalog, and Permissions. The Resource type column shows "Data cell filter" in all four rows. The permissions for the first and second rows are Describe, Drop, and Select. The permissions for the third row is Describe. Above the table is a Clear filter button and a tile indicating that the current search is for Resource type: Data cell filter. Above those is a search (text) field, and above that are Refresh, Revoke, and Grant buttons.\]](http://docs.aws.amazon.com/lake-formation/latest/dg/images/data-permissions-cell-filters.png)
------
#### [ AWS CLI ]
+ Enter a `list-permissions` command. Specify `DataCellsFilter` for the `resource` argument, and specify `DESCRIBE` or `DROP` for the `Permissions` argument and, optionally, for the `PermissionsWithGrantOption` argument.
The following example lists `DESCRIBE` permissions with the grant option on the data filter `restrict-pharma`. The results are limited to permissions granted for the principal `datalake_user1` and the `orders` table in the `sales` database in AWS account 1111-2222-3333.
```
aws lakeformation list-permissions --cli-input-json file://list-params.json
```
The following are the contents of file `grant-params.json`.
```
{
"Principal": {"DataLakePrincipalIdentifier": "arn:aws:iam::111122223333:user/datalake_user1"},
"Resource": {
"DataCellsFilter": {
"TableCatalogId": "111122223333",
"DatabaseName": "sales",
"TableName": "orders",
"Name": "restrict-pharma"
}
},
"Permissions": ["DESCRIBE"],
"PermissionsWithGrantOption": ["DESCRIBE"]
}
```
------