# 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](https://full.services/glossario/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](https://full.services/glossario/custom-post-type/) 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](https://full.services/glossario/rest-api-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](https://full.services/glossario/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. **Também conhecido como:** wpquery, wordpress query ## Termos relacionados - [The Loop WordPress](https://full.services/glossario/loop-wordpress/) - [Banco de Dados WordPress](https://full.services/glossario/banco-de-dados-wordpress/) - [Custom Post Type](https://full.services/glossario/custom-post-type/) - [REST API WordPress](https://full.services/glossario/rest-api-wordpress/) --- Glossário WordPress da FULL Services: [WP_Query](https://full.services/glossario/wp-query/)