# Column filters
A column-based filter allows you to filter [**CARTO + deck.gl** **sources and layers**](https://github.com/CartoDB/gitbook-documentation/blob/master/carto-for-developers/key-concepts/carto-for-deck.gl) dynamically, without modifying your original SQL query or resource, while fully leveraging your cloud data warehouse computing power.
{% hint style="success" %}
You can think of column filters as *WHERE* clauses wrapping your CARTO + deck.gl source, widget or layer.
{% endhint %}
Typically, column-based filters originate from user inputs in the UI of your application, most commonly from CARTO Widgets (eg: clicking in a category of a [category widget](/carto-for-developers/reference/carto-widgets-reference/models/getcategories.md) filters the map for that category)
## Using filters
Filters are an object-type property that is accepted by:
* `...TableSource` and `...QuerySource` [Data Sources](/carto-for-developers/reference/carto-widgets-reference/data-sources.md), for server-side filtering of both layers and widgets.
* All [models](/carto-for-developers/reference/carto-widgets-reference/models.md), for client-side filtering of widgets when using `...TilesetSource` and `rasterSource` [Data Sources](/carto-for-developers/reference/carto-widgets-reference/data-sources.md),
* [getDataFilterExtensionProps](#getdatafilterextensionprops), for client-side filtering of deck.gl layers.
```typescript
import {vectorTableSource} from 'carto-api-client';
// init your data source with filters
const myFilters = {};
const data = await vectorTableSource({
...cartoCredentials,
tableName: 'carto-demo-data.demo_tables.osm_pois_usa',
filters: myFilters
});
```
### Managing different sets of filters
{% hint style="success" %}
I**f your application needs to manage different sets of filters**, you can create as many filter objects as needed (`myFiltersA`, `myFiltersB`) and manage them independently.
{% endhint %}
## Filter functions
To manage your filters, use any of the following functions
### addFilter
Adds a filter to a filter object.
#### Usage
```typescript
import {vectorTableSource, addfilter, FilterType} from 'carto-api-client';
addFilter(myFilters, {
column: 'column_name',
type: FilterType.BETWEEN,
values: [[0, 100]],
owner: 'my-widget' // OPTIONAL: this filter won't affect models with 'my-widget' as filterOwner
})
```
#### Properties
* **column:** `STRING` the name of the column that this filter will be applied too
* **type:** `FilterType` the filter operation. Check [FilterType](#filtertype) for a list of accepted values.
* **values:** a set of values to filter. The expected format is dependant on the selected `type`.
* **owner** (Optional)**:** `STRING` this filter won't affect [widget models](/carto-for-developers/reference/carto-widgets-reference/models.md) that have a matching `filterOwner` property. Check [Preventing specific widgets from being filtered](#preventing-specific-widgets-from-being-filtered).
### removeFilter
Removes all filters from a filter object that match that column (or column + owner).
#### Usage
```typescript
import {vectorTableSource, removeFilter} from 'carto-api-client';
removeFilter(myFilters, {
column: 'column_name',
owner: 'my-widget' // OPTIONAL: remove only filters that originally included this owner
})
```
#### Properties
* **column:** `STRING` all filters affecting this column will be removed (unless owner is specified)
* **owner:** `STRING` if specified, the removed filters will be only the ones matching exactly the column + owner combination.
### clearFilter
Removes all filters from a filter object.
#### Usage
```typescript
import {vectorTableSource, clearFilter} from 'carto-api-client';
clearFilter(myFilters)
```
### getFilter
Returns all the current filters and its `values` for a given filter inside a filter object.
#### Usage
```typescript
import {vectorTableSource, getFilter} from 'carto-api-client';
getFilter(myFilters, {
column: 'column_name',
owner: 'my-widget' // OPTIONAL: remove only filters that originally included this owner
})
```
#### Properties
* **column:** `STRING` the name of the column we're checking for filters
* **owner:** `STRING` if specified, this function will only check filters matching exactly the column + owner combination.
### hasFilter
Returns a boolean: `true` if there are already filters that match the specified properties, `false` if there are no filters matching them.
#### Usage
```typescript
import {vectorTableSource, hasFilter} from 'carto-api-client';
hasFilter(myFilters, {
column: 'column_name',
owner: 'my-widget' // OPTIONAL: remove only filters that originally included this owner
})
```
#### Properties
* **column:** `STRING` the name of the column we're checking for filters
* **owner:** `STRING` if specified, this function will only check filters matching exactly the column + owner combination.
### FilterType
This type contains the different filter types allowed in [`addFilter`](#addfilter)
**Usage**
```typescript
import {FilterType} from 'carto-api-client';
```
**Values**
| FilterType | Expected value | Description |
|---|
FilterType.IN | number[] | string[] | Filter rows matching exactly these values. Example: ['Madrid', 'New York'] |
FilterType.BETWEEN | number[][] | Filter rows between those values. [a, b] both are included. Example: [[0, 300]] |
FilterType.CLOSED_OPEN | number[][] | Filter rows between those values. [a, b) a is included, b is not. Example: [[0, 300]] |
FilterType.TIME | number[][] | Similar to BETWEEN, but more suitable for date or timestamp columns. [a, b] both are included: ['964656085544', '1021247914455'] |
FilterType.STRING_SEARCH | string[] | Filter rows soft-matching these values. The results will be ordered with the exact matches first. Example: ['Madrid'] will also return rows with madrid or Madrid Centro |
### getDataFilterExtensionProps
Use this function to convert a valid set of filters into the properties expected by **deck.gl** [`DataFilterExtension`](https://deck.gl/docs/api-reference/extensions/data-filter-extension) to achieve GPU-based filtering (client-side filtering) of your CARTO + deck.gl layers. Useful when combined with [client-side widgets](/carto-for-developers/reference/carto-widgets-reference/server-side-vs.-client-side.md#client-side-widget-calculation).
#### Usage
```typescript
import {vectorTableSource, getDataFilterExtensionProps} from 'carto-api-client';
import {Deck} from '@deck.gl/core';
import {VectorTileLayer} from '@deck.gl/carto';
import {DataFilterExtension} from '@deck.gl/extensions';
const layers = [
new VectorTileLayer({
data: dataSource,
extensions: [new DataFilterExtension({filterSize: 4})],
...getDataFilterExtensionProps(myFilters)
// ...getDataFilterExtensionProps(filters, filtersLogicalOperator, filterSize)
})
];
```
#### Properties
* **filters:** A valid `Filters` object.
* **filtersLogicalOperator**: Indicates whether `filters` are applied following an `AND` logic or an `OR` logic. Must be a string `'and' | 'or'` .
* **fIlterSize:** An integer 2, 3, or 4. Must match the `filterSize` used to create the [`DataFilterExtension`](https://deck.gl/docs/api-reference/extensions/data-filter-extension).
## Preventing specific widgets from being filtered
Sometimes widgets are used to filter the data, for example, when clicking in a category or a pie sector. If the filter was also applied to the widget, the result could be undesired, as the widget itself would lose all the other values.
To prevent this, simply make sure to assign your widget an arbitrary string identifier via filterOwner and then use that same identifier in your addFilter calls.
**Example of a filter not applying to a widget**
import {vectorTableSource, addfilter, FilterType} from 'carto-api-client';
const myFilters = {};
const data = await vectorTableSource({
...credentials,
tableName: 'my-data.data.table',
filters: myFilters
});
addFilter(myFilters, {
column: 'column_name',
type: FilterType.BETWEEN,
values: [[0, 100]],
owner: 'cat-widget' // this filter doesn't apply
})
const excludedWidget = data.widgetSource.getCategories({
column: 'group_name',
operation: 'count',
filterOwner: 'cat-widget' // to widgets with filterOwner === 'cat-widget'
})
In this example, all layers depending on `data` would be filtered (therefore the map would be filtered) but the widget would still show all the categories, allowing for subsequent interactions.
---
# Agent Instructions: 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.carto.com/carto-for-developers/reference/filters/column-filters.md?ask=
```
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.