Gerenciar a visibilidade dos dados com filtros

Este documento explica como usar filtros para classificar e filtrar os dados mostrados em uma planilha.

Os filtros permitem classificar e filtrar os dados que aparecem ao visualizar uma planilha. Os filtros não mudam os valores dos dados na planilha. É possível usar filtros para ocultar ou classificar informações temporariamente. Os dados que correspondem aos critérios de filtro especificados não aparecem enquanto o filtro está ativado. Com as visualizações de filtro, também é possível salvar diferentes filtros nomeados e alternar entre eles quando quiser.

Para filtrar os dados retornados em uma solicitação de API do Google Sheets, use o DataFilter objeto. Para mais informações, consulte Ler, gravar e pesquisar metadados.

Casos de uso de filtros

Confira alguns exemplos de casos de uso de filtros:

  • Classificar dados por uma coluna específica. Por exemplo, classificar os registros de usuários por sobrenome.
  • Ocultar dados que atendem a uma condição específica. Por exemplo, ocultar todos os registros com mais de dois anos.
  • Ocultar dados que correspondem a um determinado valor. Por exemplo, ocultar todos os problemas com o status "fechado".

Filtro básico

O BasicFilter objeto de uma planilha é o filtro padrão aplicado sempre que alguém visualiza a planilha. Uma planilha pode ter apenas um filtro básico por página. É possível desativar o filtro básico limpando-o. Isso remove o filtro e todas as configurações dele da planilha. Se você quiser reativar o mesmo filtro, defina os critérios novamente.

Gerenciar o filtro básico

Para definir ou limpar o filtro básico, use o spreadsheets.batchUpdate método com o tipo de solicitação apropriado:

Para listar o filtro básico, use o spreadsheets.get método e defina o fields parâmetro de URL como sheets/basicFilter. O exemplo de código a seguir spreadsheets.get mostra um URL do Google Sheets com uma máscara de campo:

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

Visualizações com filtro

A FilterView é um filtro nomeado que pode ser ativado e desativado quando quiser. Uma página pode ter várias visualizações de filtro salvas, mas só é possível aplicar uma por vez. Uma página também pode conter um filtro básico e várias visualizações de filtro, mas não é possível aplicar os dois simultaneamente no mesmo intervalo de dados.

Casos de uso de visualização com filtro

Confira alguns exemplos de casos de uso de visualizações com filtro:

  • Você tem vários filtros diferentes que quer alternar ao visualizar os dados.
  • Você não tem acesso de edição a uma planilha, mas ainda quer aplicar um filtro. Nesse caso, é possível criar uma visualização com filtro temporária que só você pode ver.

  • Você quer que cada pessoa com quem compartilha a planilha visualize os dados de maneira diferente. É possível especificar a visualização com filtro que você quer aplicar fornecendo o spreadsheetId e filterViewId no URL da planilha. Para fazer isso, use o filterViewId retornado na resposta ao criar a visualização com filtro.

    O exemplo de código a seguir mostra um URL do Planilhas com uma visualização de filtro:

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

Gerenciar visualizações com filtro

Para criar, duplicar, modificar ou excluir visualizações de filtro, use o spreadsheets.batchUpdate método com o tipo de solicitação apropriado:

Para listar todas as visualizações de filtro, use o spreadsheets.get método e defina o fields parâmetro de URL como sheets/filterViews. O exemplo de código a seguir mostra um URL do Planilhas com uma máscara de campo:spreadsheets.get

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

Representação JSON de um filtro

O exemplo de código a seguir mostra a representação JSON de um FilterView objeto. O BasicFilter objeto é o mesmo, exceto que não tem os campos filterViewId e title, e não pode usar um intervalo nomeado.

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

Dados de vendas de amostra

O restante deste documento faz referência à tabela de dados de vendas de amostra a seguir:

Tabela 1. Dados de vendas de amostra
A B C D E F G
1 Categoria do item Número do modelo Custo Quantidade Região Vendedor Data de envio
2 Wheel W-24 US$ 20,50 4 Oeste Beth 01/03/2016
3 Porta D-01X US$ 15,00 2 Sul Amir 15/03/2016
4 Quadro FR-0B1 US$ 34,00 8 Leste Hannah 12/03/2016
5 Painel P-034 US$ 6,00 4 Norte Devyn 15/03/2016
6 Painel P-052 US$ 11,50 7 Leste Erik 16/05/2016
7 Wheel W-24 US$ 20,50 11 Sul Sheldon 30/04/2016
8 Mecanismo ENG-0161 US$ 330,00 2 Norte Jessie 02/07/2016

Especificações de classificação

Um filtro pode ter várias especificações de classificação. Essas especificações determinam como classificar os dados e são aplicadas na ordem especificada. O atributo especifica o índice da coluna em que a classificação será aplicada.SortSpec.dimensionIndex

O exemplo de código a seguir mostra uma especificação de classificação:

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

Quando aplicada aos dados de vendas de amostra, essa especificação classifica primeiro pela coluna "Quantidade" e, em seguida, se duas linhas tiverem a mesma quantidade, por "Data de envio."

Tabela 2. Dados de vendas classificados por duas colunas
A B C D E F G
1 Categoria do item Número do modelo Custo Quantidade Região Vendedor Data de envio
2 Porta D-01X US$ 15,00 2 Sul Amir 15/03/2016
3 Mecanismo ENG-0161 US$ 330,00 2 Norte Jessie 02/07/2016
4 Wheel W-24 US$ 20,50 4 Oeste Beth 01/03/2016
5 Painel P-034 US$ 6,00 4 Norte Devyn 15/03/2016
6 Painel P-052 US$ 11,50 7 Leste Erik 16/05/2016
7 Quadro FR-0B1 US$ 34,00 8 Leste Hannah 12/03/2016
8 Wheel W-24 US$ 20,50 11 Sul Sheldon 30/04/2016

Critérios de filtro

O FilterCriteria objeto determina quais dados da planilha são mostrados ou ocultos em um filtro básico ou visualização com filtro. Cada critério depende dos valores em uma coluna específica. Você fornece os critérios de filtro como um mapa em que as chaves são os índices das colunas e os valores são os critérios.

Para critérios especificados usando uma booleana condition, a condição precisa ser true para que os valores sejam mostrados. A condição não substitui hiddenValues. Se um valor estiver listado em hiddenValues, todas as correspondências de um valor ainda estarão ocultas.

O exemplo de código a seguir mostra um mapa de critérios de filtro:

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

Quando aplicado aos dados de vendas de amostra, esse critério mostra apenas as linhas em que o valor da coluna "Categoria do item" não é "Painel" e em que o valor da coluna "Data de envio" é anterior a "30 de abril de 2016".

Tabela 3. Dados de vendas usando critérios de filtro
A B C D E F G
1 Categoria do item Número do modelo Custo Quantidade Região Vendedor Data de envio
2 Wheel W-24 US$ 20,50 4 Oeste Beth 01/03/2016
3 Porta D-01X US$ 15,00 2 Sul Amir 15/03/2016
4 Quadro FR-0B1 US$ 34,00 8 Leste Hannah 12/03/2016

Exemplo de código de visualização com filtro

O exemplo de código a seguir mostra como criar uma visualização com filtro, duplicá-la e atualizar a versão duplicada usando os dados de vendas de amostra.

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")