LogoLogo
HomeAcademyLoginTry for free
  • Welcome
  • What's new
    • Q2 2025
    • Q1 2025
    • Q4 2024
    • Q3 2024
    • Q2 2024
    • Q1 2024
    • Q4 2023
    • Q3 2023
    • Q2 2023
    • Q1 2023
    • Q4 2022
    • Q3 2022
  • FAQs
    • Accounts
    • Migration to the new platform
    • User & organization setup
    • General
    • Builder
    • Workflows
    • Data Observatory
    • Analytics Toolbox
    • Development Tools
    • Deployment Options
    • CARTO Basemaps
    • CARTO for Education
    • Support Packages
    • Security and Compliance
  • Getting started
    • What is CARTO?
    • Quickstart guides
      • Connecting to your data
      • Creating your first map
      • Creating your first workflow
      • Developing your first application
    • CARTO Academy
  • CARTO User Manual
    • Overview
      • Creating your CARTO organization
      • CARTO Cloud Regions
      • CARTO Workspace overview
    • Maps
      • Data sources
        • Simple features
        • Spatial Indexes
        • Pre-generated tilesets
        • Rasters
        • Defining source spatial data
        • Managing data freshness
        • Changing data source location
      • Layers
        • Point
          • Grid point aggregation
          • H3 point aggregation
          • Heatmap point aggregation
          • Cluster point aggregation
        • Polygon
        • Line
        • Grid
        • H3
        • Raster
        • Zoom to layer
      • Widgets
        • Formula widget
        • Category widget
        • Pie widget
        • Histogram widget
        • Range widget
        • Time Series widget
        • Table widget
      • SQL Parameters
        • Date parameter
        • Text parameter
        • Numeric parameter
        • Publishing SQL parameters
      • Interactions
      • Legend
      • Basemaps
        • Basemap selector
      • AI Agents
      • SQL analyses
      • Map view modes
      • Map description
      • Feature selection tool
      • Search locations
      • Measure distances
      • Exporting data
      • Download PDF reports
      • Managing maps
      • Sharing and collaboration
        • Editor collaboration
        • Map preview for editors
        • Map settings for viewers
        • Comments
        • Embedding maps
        • URL parameters
      • Performance considerations
    • Workflows
      • Workflow canvas
      • Results panel
      • Components
        • Aggregation
        • Custom
        • Data Enrichment
        • Data Preparation
        • Generative AI
        • Input / Output
        • Joins
        • Parsers
        • Raster Operations
        • Spatial Accessors
        • Spatial Analysis
        • Spatial Constructors
        • Spatial Indexes
        • Spatial Operations
        • Statistics
        • Tileset Creation
        • BigQuery ML
        • Snowflake ML
        • Google Earth Engine
        • Google Environment APIs
        • Telco Signal Propagation Models
      • Data Sources
      • Scheduling workflows
      • Sharing workflows
      • Using variables in workflows
      • Executing workflows via API
      • Temporary data in Workflows
      • Extension Packages
      • Managing workflows
      • Workflows best practices
    • Data Explorer
      • Creating a map from your data
      • Importing data
        • Importing rasters
      • Geocoding data
      • Optimizing your data
    • Data Observatory
      • Terminology
      • Browsing the Spatial Data Catalog
      • Subscribing to public and premium datasets
      • Accessing free data samples
      • Managing your subscriptions
      • Accessing your subscriptions from your data warehouse
        • Access data in BigQuery
        • Access data in Snowflake
        • Access data in Databricks
        • Access data in Redshift
        • Access data in PostgreSQL
    • Connections
      • Google BigQuery
      • Snowflake
      • Databricks
      • Amazon Redshift
      • PostgreSQL
      • CARTO Data Warehouse
      • Sharing connections
      • Deleting a connection
      • Required permissions
      • IP whitelisting
      • Customer data responsibilities
    • Applications
    • Settings
      • Understanding your organization quotas
      • Activity Data
        • Activity Data Reference
        • Activity Data Examples
        • Activity Data Changelog
      • Users and Groups
        • Inviting users to your organization
        • Managing user roles
        • Deleting users
        • SSO
        • Groups
        • Mapping groups to user roles
      • CARTO Support Access
      • Customizations
        • Customizing appearance and branding
        • Configuring custom color palettes
        • Configuring your organization basemaps
        • Enabling AI Agents
      • Advanced Settings
        • Managing applications
        • Configuring S3 Bucket for Redshift Imports
        • Configuring OAuth connections to Snowflake
        • Configuring OAuth U2M connections to Databricks
        • Configuring S3 Bucket integration for RDS for PostgreSQL Exports in Builder
        • Configuring Workload Identity Federation for BigQuery
      • Data Observatory
      • Deleting your organization
    • Developers
      • Managing Credentials
        • API Base URL
        • API Access Tokens
        • SPA OAuth Clients
        • M2M OAuth Clients
      • Named Sources
  • Data and Analysis
    • Analytics Toolbox Overview
    • Analytics Toolbox for BigQuery
      • Getting access
        • Projects maintained by CARTO in different BigQuery regions
        • Manual installation in your own project
        • Installation in a Google Cloud VPC
        • Core module
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • cpg
        • data
        • http_request
        • import
        • geohash
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • routing
        • s2
        • statistics
        • telco
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release notes
      • About Analytics Toolbox regions
    • Analytics Toolbox for Snowflake
      • Getting access
        • Native App from Snowflake's Marketplace
        • Manual installation
      • Key concepts
        • Spatial indexes
        • Tilesets
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • data
        • http_request
        • import
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release Notes
    • Analytics Toolbox for Databricks
      • Getting access
        • Personal (former Single User) cluster
        • Standard (former Shared) cluster
      • Reference
        • lds
        • tiler
      • Guides
      • Release Notes
    • Analytics Toolbox for Redshift
      • Getting access
        • Manual installation in your database
        • Installation in an Amazon Web Services VPC
        • Core version
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • clustering
        • constructors
        • data
        • http_request
        • import
        • lds
        • placekey
        • processing
        • quadbin
        • random
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
      • Release Notes
    • Analytics Toolbox for PostgreSQL
      • Getting access
        • Manual installation
        • Core version
      • Key concepts
        • Tilesets
        • Spatial Indexes
      • SQL Reference
        • h3
        • quadbin
        • tiler
      • Guides
        • Creating spatial index tilesets
        • Running queries from Builder
      • Release Notes
    • CARTO + Python
      • Installation
      • Authentication Methods
      • Visualizing Data
      • Working with Data
        • How to work with your data in the CARTO Data Warehouse
        • How to access your Data Observatory subscriptions
        • How to access CARTO's Analytics Toolbox for BigQuery and create visualizations via Python notebooks
        • How to access CARTO’s Analytics Toolbox for Snowflake and create visualizations via Python notebooks
        • How to visualize data from Databricks
      • Reference
    • CARTO QGIS Plugin
  • CARTO for Developers
    • Overview
    • Key concepts
      • Architecture
      • Libraries and APIs
      • Authentication methods
        • API Access Tokens
        • OAuth Access Tokens
        • OAuth Clients
      • Connections
      • Data sources
      • Visualization with deck.gl
        • Basemaps
          • CARTO Basemap
          • Google Maps
            • Examples
              • Gallery
              • Getting Started
              • Basic Examples
                • Hello World
                • BigQuery Tileset Layer
                • Data Observatory Tileset Layer
              • Advanced Examples
                • Arc Layer
                • Extrusion
                • Trips Layer
            • What's New
          • Amazon Location
            • Examples
              • Hello World
              • CartoLayer
            • What's New
      • Charts and widgets
      • Filtering and interactivity
      • Integrating Builder maps in your application
      • Summary
    • Quickstart
      • Make your first API call
      • Visualize your first dataset
      • Create your first widget
    • Guides
      • Build a public application
      • Build a private application
      • Build a private application using SSO
      • Visualize massive datasets
      • Integrate CARTO in your existing application
      • Use Boundaries in your application
      • Avoid exposing SQL queries with Named Sources
      • Managing cache in your CARTO applications
    • Reference
      • Deck (@deck.gl reference)
      • Data Sources
        • vectorTableSource
        • vectorQuerySource
        • vectorTilesetSource
        • h3TableSource
        • h3QuerySource
        • h3TilesetSource
        • quadbinTableSource
        • quadbinQuerySource
        • quadbinTilesetSource
        • rasterSource
        • boundaryTableSource
        • boundaryQuerySource
      • Layers (@deck.gl/carto)
      • Widgets
        • Data Sources
        • Server-side vs. client-side
        • Models
          • getFormula
          • getCategories
          • getHistogram
          • getRange
          • getScatter
          • getTimeSeries
          • getTable
      • Filters
        • Column filters
        • Spatial filters
      • fetchMap
      • CARTO APIs Reference
    • Release Notes
    • Examples
    • CARTO for React
      • Guides
        • Getting Started
        • Views
        • Data Sources
        • Layers
        • Widgets
        • Authentication and Authorization
        • Basemaps
        • Look and Feel
        • Query Parameters
        • Code Generator
        • Sample Applications
        • Deployment
        • Upgrade Guide
      • Examples
      • Library Reference
        • Introduction
        • API
        • Auth
        • Basemaps
        • Core
        • Redux
        • UI
        • Widgets
      • Release Notes
  • CARTO Self-Hosted
    • Overview
    • Key concepts
      • Architecture
      • Deployment requirements
    • Quickstarts
      • Single VM deployment (Kots)
      • Orchestrated container deployment (Kots)
      • Advanced Orchestrated container deployment (Helm)
    • Guides
      • Guides (Kots)
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Use Workload Identity in GCP
        • High availability configuration for CARTO Self-hosted
        • Configure your custom service account
      • Guides (Helm)
        • Configure your own buckets (Helm)
        • Configure an external in-memory cache (Helm)
        • Enable Google Basemaps (Helm)
        • Enable the CARTO Data Warehouse (Helm)
        • Configure an external proxy (Helm)
        • Enable BigQuery OAuth connections (Helm)
        • Configure Single Sign-On (SSO) (Helm)
        • Use Workload Identity in GCP (Helm)
        • Use EKS Pod Identity in AWS (Helm)
        • Enable Redshift imports (Helm)
        • Migrating CARTO Self-hosted installation to an external database (Helm)
        • Advanced customizations (Helm)
        • Configure your custom service account (Helm)
    • Maintenance
      • Maintenance (Kots)
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
        • Change the Admin Console password
      • Maintenance (Helm)
        • Monitoring (Helm)
        • Rotating keys (Helm)
        • Uninstall (Helm)
        • Backups (Helm)
        • Updates (Helm)
    • Support
      • Get debug information for Support (Kots)
      • Get debug information for Support (Helm)
    • CARTO Self-hosted Legacy
      • Key concepts
        • Architecture
        • Deployment requirements
      • Quickstarts
        • Single VM deployment (docker-compose)
      • Guides
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Enable Redshift imports
        • Configure your custom service account
        • Advanced customizations
        • Migrating CARTO Self-Hosted installation to an external database
      • Maintenance
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
      • Support
    • Release Notes
  • CARTO Native App for Snowflake Containers
    • Deploying CARTO using Snowflake Container Services
  • Get Help
    • Legal & Compliance
    • Previous libraries and components
    • Migrating your content to the new CARTO platform
Powered by GitBook
On this page
  • Using filters
  • Managing different sets of filters
  • Filter functions
  • addFilter
  • removeFilter
  • clearFilter
  • getFilter
  • hasFilter
  • FilterType
  • getDataFilterExtensionProps
  • Preventing specific widgets from being filtered

Was this helpful?

Export as PDF
  1. CARTO for Developers
  2. Reference
  3. Filters

Column filters

PreviousFiltersNextSpatial filters

Last updated 2 months ago

Was this helpful?

A column-based filter allows you to filter dynamically, without modifying your original SQL query or resource, while fully leveraging your cloud data warehouse computing power.

You can think of column filters as WHERE clauses wrapping your CARTO + deck.gl source, widget or layer.

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 filters the map for that category)

Using filters

Filters are an object-type property that is accepted by:

  • ...TableSource and ...QuerySource , for server-side filtering of both layers and widgets.

  • All , for client-side filtering of widgets when using ...TilesetSource and rasterSource ,

  • , for client-side filtering of deck.gl layers.

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

If your application needs to manage different sets of filters, you can create as many filter objects as needed (myFiltersA, myFiltersB) and manage them independently.

Filter functions

To manage your filters, use any of the following functions

addFilter

Adds a filter to a filter object.

Usage

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

  • values: a set of values to filter. The expected format is dependant on the selected type.

removeFilter

Removes all filters from a filter object that match that column (or column + owner).

Usage

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

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

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

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

Usage

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

Usage

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' .

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.

type: FilterType the filter operation. Check for a list of accepted values.

owner (Optional): STRING this filter won't affect that have a matching filterOwner property. Check .

This type contains the different filter types allowed in

Use this function to convert a valid set of filters into the properties expected by deck.gl to achieve GPU-based filtering (client-side filtering) of your CARTO + deck.gl layers. Useful when combined with .

fIlterSize: An integer 2, 3, or 4. Must match the filterSize used to create the .

DataFilterExtension
CARTO + deck.gl sources and layers
category widget
Data Sources
models
Data Sources
getDataFilterExtensionProps
FilterType
widget models
Preventing specific widgets from being filtered
addFilter
DataFilterExtension
client-side widgets