Administra la visibilidad de los datos con filtros

En este documento, se explica cómo usar filtros para ordenar y filtrar los datos que se muestran en una hoja de cálculo.

Los filtros te permiten ordenar y filtrar los datos que ves cuando consultas una hoja de cálculo. Los filtros no cambian los valores de datos en tu hoja de cálculo. Puedes usar filtros para ocultar o ordenar información de forma temporal. Los datos que coinciden con los criterios de filtro especificados no aparecen mientras el filtro está activado. Con las vistas de filtro, también puedes guardar diferentes filtros con nombre y cambiar entre ellos cuando quieras.

Para filtrar los datos que se muestran en una solicitud de la API de Hojas de cálculo de Google, usa el DataFilter objeto. Para obtener más información, consulta Cómo leer, escribir y buscar metadatos.

Casos de uso de filtros

A continuación, se incluyen algunos ejemplos de casos de uso de filtros:

  • Ordenar datos por una columna en particular (p. ej., ordenar los registros de usuarios por apellido )
  • Ocultar datos que cumplan con una condición específica (p. ej., ocultar todos los registros de más de dos años)
  • Ocultar datos que coincidan con un valor determinado (p. ej., ocultar todos los problemas con el estado "cerrado")

Filtro básico

El BasicFilter objeto de una hoja de cálculo es el filtro predeterminado que se aplica cada vez que alguien consulta la hoja de cálculo. Una hoja de cálculo puede tener solo un filtro básico por hoja. Para desactivar el filtro básico , bórralo. Esto quita el filtro y toda su configuración de la hoja de cálculo. Si quieres volver a activar el mismo filtro, debes volver a establecer los criterios.

Administra el filtro básico

Para establecer o borrar el filtro básico, usa el spreadsheets.batchUpdate método con el tipo de solicitud adecuado:

Para enumerar el filtro básico, usa el spreadsheets.get método y establece el fields parámetro de URL en sheets/basicFilter. En el siguiente spreadsheets.get ejemplo de código, se muestra una URL de Hojas de cálculo de Google con una máscara de campo:

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/basicFilter

Vistas de filtro

A FilterView es un filtro con nombre que puedes activar y desactivar cuando quieras. Una hoja puede tener varias vistas de filtro guardadas, pero solo puedes aplicar una a la vez. Una hoja también puede contener un filtro básico y varias vistas de filtro, pero no puedes aplicar ambos simultáneamente en el mismo rango de datos.

Casos de uso de vistas de filtro

A continuación, se incluyen algunos ejemplos de casos de uso de vistas de filtro:

  • Tienes varios filtros diferentes entre los que quieres cambiar cuando ves los datos.
  • No tienes acceso de edición a una hoja de cálculo, pero quieres aplicar un filtro. En este caso, puedes crear una vista de filtro temporal que solo sea visible para ti.

  • Quieres que cada persona con la que compartes tu hoja de cálculo vea los datos de manera diferente. Para especificar la vista de filtro que quieres aplicar, proporciona el spreadsheetId y filterViewId en la URL de la hoja de cálculo. Para ello, usa el filterViewId que se muestra en la respuesta cuando creas la vista de filtro.

    En el siguiente ejemplo de código, se muestra una URL de Hojas de cálculo con una vista de filtro:

    https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0&fvid=FILTER_VIEW_ID

Administra vistas de filtro

Para crear, duplicar, modificar o borrar vistas de filtro, usa el spreadsheets.batchUpdate método con el tipo de solicitud adecuado:

Para enumerar todas tus vistas de filtro, usa el spreadsheets.get método y establece el fields parámetro de URL en sheets/filterViews. En el siguiente ejemplo de código de spreadsheets.get, se muestra una URL de Hojas de cálculo con una máscara de campo:

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/filterViews

Representación JSON de un filtro

En el siguiente ejemplo de código, se muestra la representación JSON de un FilterView objeto. El BasicFilter objeto es el mismo, excepto que no tiene los campos filterViewId y title, y no puede usar un rango con nombre.

{
  "filterViewId": number,
  "title": string,
  "range": {
    object(GridRange)
  },
  "namedRangeId": string,
  "sortSpecs": [
    {
      object(SortSpec)
    }
  ],
  "criteria": {
    string: {
      object(FilterCriteria)
    },
    ...
  }
}

Datos de ventas de muestra

En el resto de este documento, se hace referencia a la siguiente tabla de datos de ventas de muestra:

Tabla 1. Datos de ventas de muestra
A B C D E F G
1 Item Category Número de modelo Costo Cantidad Región Vendedor Fecha de envío
2 Rueda de la fortuna W-24 USD 20.50 4 Oeste Beth 1/3/2016
3 Puerta D-01X USD 15.00 2 Sur Amir 15/3/2016
4 Marco FR-0B1 USD 34.00 8 Este Hannah 12/3/2016
5 Panel P-034 USD 6.00 4 Norte Devyn 15/3/2016
6 Panel P-052 USD 11.50 7 Este Erik 16/5/2016
7 Rueda de la fortuna W-24 USD 20.50 11 Sur Sheldon 30/4/2016
8 Motor ENG-0161 USD 330.00 2 Norte Jessie 2/7/2016

Especificaciones de orden

Un filtro puede tener varias especificaciones de orden. Estas especificaciones determinan cómo ordenar los datos y se aplican en el orden especificado. El atributo especifica el índice de columna al que se debe aplicar la ordenación.SortSpec.dimensionIndex

En el siguiente ejemplo de código, se muestra una especificación de orden:

[
  {
    "dimensionIndex": 3,
    "sortOrder": "ASCENDING"
  },
  {
    "dimensionIndex": 6,
    "sortOrder": "ASCENDING"
  }
]

Cuando se aplica a los datos de ventas de muestra, esta especificación ordena primero por la columna "Cantidad" y, luego, si dos filas tienen la misma cantidad, por "Fecha de envío".

Tabla 2. Datos de ventas ordenados por dos columnas
A B C D E F G
1 Item Category Número de modelo Costo Cantidad Región Vendedor Fecha de envío
2 Puerta D-01X USD 15.00 2 Sur Amir 15/3/2016
3 Motor ENG-0161 USD 330.00 2 Norte Jessie 2/7/2016
4 Rueda de la fortuna W-24 USD 20.50 4 Oeste Beth 1/3/2016
5 Panel P-034 USD 6.00 4 Norte Devyn 15/3/2016
6 Panel P-052 USD 11.50 7 Este Erik 16/5/2016
7 Marco FR-0B1 USD 34.00 8 Este Hannah 12/3/2016
8 Rueda de la fortuna W-24 USD 20.50 11 Sur Sheldon 30/4/2016

Criterios de filtro

El FilterCriteria objeto determina qué datos de la hoja de cálculo se muestran o se ocultan en un filtro básico o vista de filtro. Cada criterio depende de los valores de una columna específica. Proporcionas los criterios de filtro como un mapa en el que las claves son los índices de columna y los valores son los criterios.

Para los criterios especificados con una booleana condition, la condición debe ser true para que se muestren los valores. La condición no anula hiddenValues. Si un valor aparece en hiddenValues, todas las coincidencias de un valor aún están ocultas.

En el siguiente ejemplo de código, se muestra un mapa de criterios de filtro:

{
  0: {
    'hiddenValues': ['Panel']
  },
  6: {
    'condition': {
      'type': 'DATE_BEFORE',
      'values': {
        'userEnteredValue': '4/30/2016'
      }
    }
  }
}

Cuando se aplica a los datos de ventas de muestra, este criterio solo muestra las filas en las que el valor de la columna "Item Category" no es "Panel" y en las que el valor de la columna "Fecha de envío" es anterior al "30 de abril de 2016".

Tabla 3. Datos de ventas con criterios de filtro
A B C D E F G
1 Item Category Número de modelo Costo Cantidad Región Vendedor Fecha de envío
2 Rueda de la fortuna W-24 USD 20.50 4 Oeste Beth 1/3/2016
3 Puerta D-01X USD 15.00 2 Sur Amir 15/3/2016
4 Marco FR-0B1 USD 34.00 8 Este Hannah 12/3/2016

Ejemplo de código de vista de filtro

En el siguiente ejemplo de código, se muestra cómo crear una vista de filtro, duplicarla y luego, actualizar la versión duplicada con los datos de ventas de muestra.

Java

sheets/snippets/src/main/java/SheetsFilterViews.java
/*
 * Dependencies (Maven):
 * com.google.apis:google-api-services-sheets:v4-rev20220927-2.0.0
 * com.google.auth:google-auth-library-oauth2-http:1.19.0
 */

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.*;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.*;

public class SheetsFilterViews {

    public static void main(String... args) {
        filterViews("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k");
    }

    public static void filterViews(String spreadsheetId) {
        try {
            // Load pre-authorized user credentials from the environment.
            // TODO(developer) - See https://developers.google.com/identity for guides on implementing OAuth2.
            GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
                    .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));

            Sheets service = new Sheets.Builder(
                    GoogleNetHttpTransport.newTrustedTransport(),
                    GsonFactory.getDefaultInstance(),
                    new HttpCredentialsAdapter(credentials))
                    .setApplicationName("Sheets Filter Views Sample")
                    .build();

            // --- Step 1: Add Filter View ---
            GridRange myRange = new GridRange()
                    .setSheetId(0)
                    .setStartRowIndex(0)
                    .setStartColumnIndex(0);

            // Construct Criteria for Column 0 (Hidden Values)
            FilterCriteria criteria0 = new FilterCriteria()
                    .setHiddenValues(Collections.singletonList("Panel"));

            // Construct Criteria for Column 6 (Date Condition)
            ConditionValue dateValue = new ConditionValue().setUserEnteredValue("4/30/2016");
            BooleanCondition dateCondition = new BooleanCondition()
                    .setType("DATE_BEFORE")
                    .setValues(Collections.singletonList(dateValue));
            FilterCriteria criteria6 = new FilterCriteria().setCondition(dateCondition);

            // Map criteria to column indices (Note: keys are Strings in Java map)
            Map<String, FilterCriteria> criteriaMap = new HashMap<>();
            criteriaMap.put("0", criteria0);
            criteriaMap.put("6", criteria6);

            FilterView filterView = new FilterView()
                    .setTitle("Sample Filter")
                    .setRange(myRange)
                    .setSortSpecs(Collections.singletonList(
                            new SortSpec().setDimensionIndex(3).setSortOrder("DESCENDING")
                    ))
                    .setCriteria(criteriaMap);

            // --- Step 1: Add Filter View ---
            // (Request construction remains the same)
            // ...
            AddFilterViewRequest addFilterViewRequest = new AddFilterViewRequest().setFilter(filterView);

            BatchUpdateSpreadsheetRequest batchRequest1 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setAddFilterView(addFilterViewRequest)));

            BatchUpdateSpreadsheetResponse response1 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest1)
                    .execute();

            if (response1.getReplies() == null || response1.getReplies().isEmpty()) {
                System.err.println("Error: No replies returned from AddFilterView request.");
                return;
            }

            Response reply1 = response1.getReplies().get(0);
            if (reply1.getAddFilterView() == null || reply1.getAddFilterView().getFilter() == null) {
                 System.err.println("Error: Response did not contain AddFilterView data.");
                 return;
            }

            int filterId = reply1.getAddFilterView().getFilter().getFilterViewId();

            // --- Step 2: Duplicate Filter View ---
            DuplicateFilterViewRequest duplicateRequest = new DuplicateFilterViewRequest()
                    .setFilterId(filterId);

            BatchUpdateSpreadsheetRequest batchRequest2 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setDuplicateFilterView(duplicateRequest)));

            BatchUpdateSpreadsheetResponse response2 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest2)
                    .execute();

            if (response2.getReplies() == null || response2.getReplies().isEmpty()) {
                 System.err.println("Error: No replies returned from DuplicateFilterView request.");
                 return;
            }

            Response reply2 = response2.getReplies().get(0);
            if (reply2.getDuplicateFilterView() == null || reply2.getDuplicateFilterView().getFilter() == null) {
                System.err.println("Error: Response did not contain DuplicateFilterView data.");
                return;
            }

            int newFilterId = reply2.getDuplicateFilterView().getFilter().getFilterViewId();

            // --- Step 3: Update Filter View ---
            // Extract the new ID from the duplicate response
            int newFilterId = response2.getReplies().get(0)
                    .getDuplicateFilterView().getFilter().getFilterViewId();

            // Create update criteria
            Map<String, FilterCriteria> updateCriteriaMap = new HashMap<>();
            updateCriteriaMap.put("0", new FilterCriteria()); // Empty criteria

            ConditionValue numValue = new ConditionValue().setUserEnteredValue("5");
            BooleanCondition numCondition = new BooleanCondition()
                    .setType("NUMBER_GREATER")
                    .setValues(Collections.singletonList(numValue));
            updateCriteriaMap.put("3", new FilterCriteria().setCondition(numCondition));

            FilterView updateFilterView = new FilterView()
                    .setFilterViewId(newFilterId)
                    .setTitle("Updated Filter")
                    .setCriteria(updateCriteriaMap);

            UpdateFilterViewRequest updateRequest = new UpdateFilterViewRequest()
                    .setFilter(updateFilterView)
                    .setFields("criteria,title");

            BatchUpdateSpreadsheetRequest batchRequest3 = new BatchUpdateSpreadsheetRequest()
                    .setRequests(Collections.singletonList(new Request().setUpdateFilterView(updateRequest)));

            BatchUpdateSpreadsheetResponse response3 = service.spreadsheets()
                    .batchUpdate(spreadsheetId, batchRequest3)
                    .execute();

            System.out.println(response3.toPrettyString());

        } catch (IOException | GeneralSecurityException e) {
            System.err.println("An error occurred: " + e);
        }
    }
}

Python

sheets/snippets/sheets_filter_views.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def filter_views(spreadsheet_id):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)

    my_range = {
        "sheetId": 0,
        "startRowIndex": 0,
        "startColumnIndex": 0,
    }
    addfilterviewrequest = {
        "addFilterView": {
            "filter": {
                "title": "Sample Filter",
                "range": my_range,
                "sortSpecs": [{
                    "dimensionIndex": 3,
                    "sortOrder": "DESCENDING",
                }],
                "criteria": {
                    0: {"hiddenValues": ["Panel"]},
                    6: {
                        "condition": {
                            "type": "DATE_BEFORE",
                            "values": {"userEnteredValue": "4/30/2016"},
                        }
                    },
                },
            }
        }
    }

    body = {"requests": [addfilterviewrequest]}
    addfilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )

    duplicatefilterviewrequest = {
        "duplicateFilterView": {
            "filterId": addfilterviewresponse["replies"][0]["addFilterView"][
                "filter"
            ]["filterViewId"]
        }
    }

    body = {"requests": [duplicatefilterviewrequest]}
    duplicatefilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )

    updatefilterviewrequest = {
        "updateFilterView": {
            "filter": {
                "filterViewId": duplicatefilterviewresponse["replies"][0][
                    "duplicateFilterView"
                ]["filter"]["filterViewId"],
                "title": "Updated Filter",
                "criteria": {
                    0: {},
                    3: {
                        "condition": {
                            "type": "NUMBER_GREATER",
                            "values": {"userEnteredValue": "5"},
                        }
                    },
                },
            },
            "fields": {"paths": ["criteria", "title"]},
        }
    }

    body = {"requests": [updatefilterviewrequest]}
    updatefilterviewresponse = (
        service.spreadsheets()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )
    print(str(updatefilterviewresponse))
  except HttpError as error:
    print(f"An error occurred: {error}")


if __name__ == "__main__":
  # Pass: spreadsheet_id
  filter_views("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k")