Filtros

Com os filtros, você pode classificar e filtrar os dados que aparecem quando você acessa uma planilha. Os filtros não mudam os valores de dados na planilha. Você pode 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, você também pode salvar filtros nomeados diferentes e alternar entre eles quando quiser.

Confira alguns exemplos de casos de uso de filtros:

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

Filtro básico

O BasicFilter de uma planilha é o filtro padrão aplicado sempre que alguém acessa a planilha. Uma planilha pode ter um filtro básico por folha. Para desativar o filtro básico, ele precisa ser limpo. 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 método spreadsheets.batchUpdate com o tipo de solicitação adequado:

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

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

Visualizações com filtro

Um FilterView é um filtro nomeado que pode ser ativado e desativado quando você quiser. Uma planilha pode ter várias visualizações de filtro, mas você só pode aplicar uma de cada vez.

Confira alguns exemplos de casos de uso para visualizações de 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 quer aplicar um filtro. Nesse caso, você pode criar uma visualização de filtro temporária que só será visível para você.

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

    O exemplo de código a seguir mostra um URL das Planilhas Google com uma visualização filtrada:

    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 método spreadsheets.batchUpdate com o tipo de solicitação apropriado:

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

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

Representação do filtro

O exemplo de código abaixo mostra a representação JSON de um objeto FilterView. O objeto BasicFilter é o mesmo, exceto por não ter os campos filterViewId e title e não poder usar um intervalo nomeado.

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

Exemplo

O restante deste documento faz referência ao exemplo de tabela de dados de vendas abaixo:

Tabela 1. Exemplo de dados de vendas
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 2/7/2016

Especificações de ordenaçã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 SortSpec.dimensionIndex especifica o índice da coluna em que a classificação será aplicada.

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 exemplos de dados de vendas, essa especificação ordena primeiro por "Quantidade" e, 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 2/7/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 método FilterCriteria determina quais dados da planilha são mostrados ou ocultos em um filtro básico ou visualização de 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 de coluna e os valores são os critérios.

Para critérios especificados usando um condition booleano, a condição precisa ser True para que os valores sejam mostrados. A condição não substitui hiddenValues. Se um valor for listado em hiddenValues, todas as correspondências para 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 exemplos de dados de vendas, esse critério só mostra linhas em que a "Categoria do item" não é "Painel" e em que a "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

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

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