English 中文 العربية 日本語 Português

useQuery useQuery: Busca de Dados

Última atualização: 2026-11-03

useQuery useQuery: Busca de Dados

useQuery do TanStack Query gerencia todo o ciclo de vida da requisição mais o cache: ele deduplica automaticamente, refaz a busca em segundo plano, staleTime controla por quanto tempo os dados permanecem frescos, e invalidateQueries marca entradas como obsoletas para que sejam buscadas novamente. O componente apenas declara quais dados precisa e deixa o resto para a biblioteca, então a mesma query nunca é buscada duas vezes para dois componentes.

GrupoDados e Engenharia
TipoHook
DesdeTanStack Query v5

ℹ️ Informação O editor transpila JSX para JavaScript e renderiza a UI real na sandbox; os componentes são montados automaticamente — sem render manual.

📝 Sintaxe

import { useQuery } from '@tanstack/react-query'

const { data, isPending, isError, error, refetch } = useQuery({
  queryKey: ['todo', id],          // cache key: a change switches to or refetches the query
  queryFn: () => fetch('/api/todos/' + id).then(r => r.json()),
  staleTime: 30_000                // fresh for 30 seconds, no refetch needed
})
// isPending: first load without a cache; isFetching: any background refetch

⚙️ Parâmetros

queryKeyA chave de cache (um array): em ['todos', id], um id alterado troca para a entrada de cache correspondente e refaz a busca, enquanto uma chave idêntica reutiliza o cache.
staleTimePor quanto tempo os dados permanecem frescos (milissegundos): dentro dessa janela, uma remontagem usa o cache diretamente; depois, uma remontagem atualiza silenciosamente em segundo plano (stale-while-revalidate).

Retorna：Retorna o estado da query como { data, isPending, isError, error, refetch, isFetching }: data contém os dados mais recentes e refetch invalida a entrada e a busca novamente manualmente.

▶ Exemplo

O exemplo roda direto: renderiza automaticamente ao expandir e edições valem na hora.

Saída：

A primeira leitura espera 0,8 segundo; depois, "Ler" retorna instantaneamente porque o cache Map acerta, e "refetch" força uma nova requisição e atualiza o cache — as ideias centrais por trás de staleTime e invalidação (demonstração simulada).
▶ Experimente

💡 Pontos-chave

💡 Dica Coloque toda dependência na queryKey (['todos', filter, page]) e a biblioteca refaz a busca automaticamente quando elas mudam — esse é o array de dependências de um useEffect entregue à camada de cache.
⚠️ Aviso A queryKey deve conter todo parâmetro de requisição e precisa ser serializável; deixar um de fora faz dados diferentes compartilharem uma chave de cache e você acaba com o registro errado sob o nome errado.
ℹ️ Informação A v5 renomeou loading para isPending: isPending significa a primeira carga sem cache, enquanto isFetching também abrange uma atualização em segundo plano. Os dois significam coisas diferentes.
tanstack-mutation http-three-states usefetch-hook abortcontroller
Mais casos em breve.

📚 Tutoriais Relacionados

TanStack Query
Lição 20: cache, invalidação e atualizações otimistas.

❓ Perguntas Frequentes

P Qual a diferença entre staleTime e gcTime (o antigo cacheTime)?
R staleTime decide por quanto tempo os dados contam como frescos e não precisam de nova busca, enquanto gcTime decide por quanto tempo uma entrada de cache não usada é mantida antes de ser coletada como lixo. O primeiro dirige a frequência de requisição, o segundo o uso de memória.
P Como atualizo os dados após eles mudarem?
R Chame refetch(), ou use queryClient.invalidateQueries({ queryKey }) para marcar as queries relacionadas como obsoletas, e os componentes correspondentes refazem a busca em segundo plano automaticamente.
P Por que a queryKey é um array e não uma string?
R Um array é uma chave estruturada: ['todos', 2] e ['todos', 3] são distinguidos exatamente, e você pode invalidar toda query sob o prefixo ['todos'] de uma vez, o que mantém o cache gerenciável em camadas.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%