WP_Query

WP_Query WordPress é a classe PHP central do WordPress responsável por construir e executar consultas ao banco de dados. É o motor por trás de praticamente toda página renderizada — quando você abre a home, o WordPress dispara uma WP_Query para buscar os posts; quando entra em um single, é WP_Query novamente. Para desenvolvedores, é a forma oficial e recomendada de criar consultas customizadas para qualquer tipo de conteúdo: posts, páginas, custom post types, busca, taxonomias.

O que é WP_Query

WP_Query é uma classe PHP definida em wp-includes/class-wp-query.php, parte do core do WordPress desde a versão 1.5 (2005). Encapsula a lógica de transformar parâmetros em queries SQL, executar contra o banco MySQL ou MariaDB, e devolver o resultado em formato amigável de objetos WP_Post.

O ciclo de uso é simples. Você instancia a classe passando um array de parâmetros, ela monta o SQL automaticamente, executa, e devolve os posts encontrados. Você itera com have_posts() e the_post() — métodos que avançam pelo resultado e populam as variáveis globais que template tags usam. Em três linhas de código, faz consulta wordpress complexa.

A pergunta sobre o que é uma consulta wordpress se resume a isto: uma instância de WP_Query. Mesmo quando você não escreve explicitamente, o WordPress está executando uma WP_Query global por trás dos panos para popular o Loop principal de cada página. A variável global $wp_query contém essa instância automática.

Para entender o impacto, considere a alternativa: escrever queries SQL puras via wpdb. Funciona, mas perde toda a inteligência do WordPress — caching de queries, hooks de filtro, integração com plugins, segurança contra SQL injection. WP_Query entrega tudo isso de fábrica, e por isso é o caminho recomendado para 99% dos casos.

Estrutura básica de uma WP_Query

O padrão clássico tem quatro etapas. Instanciar a classe com os parâmetros desejados. Verificar se há posts (have_posts). Iterar com the_post() para popular variáveis globais. Restaurar o estado original via wp_reset_postdata() ao final.

Em código:

$args = array(‘post_type’ => ‘produto’, ‘posts_per_page’ => 10);
$query = new WP_Query($args);
if ($query->have_posts()) {
  while ($query->have_posts()) {
    $query->the_post();
    the_title();
  }
}
wp_reset_postdata();

O wp_reset_postdata() é crítico e frequentemente esquecido por iniciantes. Quando você roda uma WP_Query secundária dentro de uma página que já tem o Loop principal, as variáveis globais ficam apontando para o último post da query secundária. Sem reset, the_title() depois da query custom retorna o título errado. Reset restaura o post original, e tudo volta a funcionar.

Para queries que precisam apenas saber quantos posts batem (sem renderizar nada), use $query->found_posts. Retorna o número total. Útil para mostrar contadores, validar disponibilidade de conteúdo, ou pular renderização quando não há resultado. Combine com Loop WordPress para o fluxo completo de exibição.

Parâmetros mais usados

Os parâmetros principais cobrem a maioria dos casos. post_type define o tipo (post, page, product, ou qualquer custom post type registrado). posts_per_page limita a quantidade. orderby e order definem ordenação (date, title, rand, ASC, DESC). offset pula registros — útil em paginação manual.

Para filtros por categoria e tag, use category_name, category__in, tag, tag__in. Para taxonomias customizadas, use tax_query com array de configuração. Combinações poderosas são possíveis: “posts do post type “produto”, da taxonomia “departamento”, com terms específicos, ordenados por preço crescente, exibindo 20 por página”.

Para meta queries (campos personalizados), use meta_query. Permite filtrar e ordenar por valor de custom field. “Mostre os produtos onde meta_key = ‘destaque’ e meta_value = ‘sim'”. Combinado com Custom Post Types e ACF, abre cenário gigantesco de possibilidades em sites com lógica de negócio complexa.

Para busca de texto, use s (string de busca). “Mostre posts cujo título ou conteúdo contenha ‘wordpress'”. Para data, use date_query. “Mostre posts dos últimos 7 dias” ou “posts de janeiro de 2024 em diante”. Para autor, use author ou author_name. A documentação oficial lista 50+ parâmetros — vale consultar quando montar query complexa.

WP_Query vs query_posts vs get_posts

WP_Query é a classe pura — você cria instância e usa. É o caminho mais flexível, com isolamento total: a query customizada não interfere com a query principal da página. Recomendado pela documentação oficial para qualquer query secundária dentro de templates ou plugins.

query_posts() é uma função antiga (existe desde 2.0) que modifica a query principal da página. Quando você chama query_posts no meio de um template, está reescrevendo a query original. É perigoso: quebra paginação, confunde plugins de SEO, gera bugs em arquivos de arquivo. A recomendação oficial desde 2010 é evitar query_posts em qualquer cenário — use pre_get_posts via hook se precisar modificar a query principal.

get_posts() é uma função wrapper que simplifica casos simples. Aceita os mesmos parâmetros, mas devolve um array puro de objetos WP_Post sem a estrutura de Loop. É útil para listas pequenas onde você não precisa de have_posts/the_post — apenas quer iterar com foreach. Tem desempenho ligeiramente diferente (suppress_filters por padrão é true) e não dispara alguns hooks que WP_Query dispara.

A regra prática: WP_Query para queries complexas dentro de templates, especialmente quando você quer respeitar plugins e filtros. get_posts para listas curtas e simples (“últimos 5 posts da categoria X”). pre_get_posts hook para modificar a query principal sem instanciar nada. query_posts: nunca.

Para projetos que combinam WP_Query com integrações via REST API do WordPress e querem performance otimizada em queries pesadas (catálogos com 50.000 produtos, sites editoriais com 500.000 posts), considere indexação de meta fields, cache de objeto via Redis e otimização de banco — sem essa camada, queries complexas viram gargalo de servidor.

Para projetos que usam WP_Query intensivamente combinada com banco de dados WordPress bem ajustado, a FULL Services entrega o ACF licenciado e configurado dentro do painel, peça-chave para criar campos customizados que alimentam meta_query de forma estruturada, junto com infraestrutura otimizada para sustentar queries pesadas em produção. É a forma de transformar WP_Query em ferramenta de catálogos e bibliotecas WordPress de verdade, sem virar gargalo.