Tópico 7 — WP_Query e Meta Queries | Guia Técnico WordPress, Banco de Dados e Next.js

1. O que é a WP_Query

A classe WP_Query é o motor que gera as consultas no WordPress. Ela define quais posts, páginas ou conteúdos serão carregados com base em parâmetros. Entender sua estrutura é essencial para controlar o que o site exibe.

Objetivo aprender a criar consultas personalizadas e a manipular resultados sem quebrar o loop principal.

2. Exemplo básico de WP_Query

Consulta simples

<?php
$args = [
  'post_type'      => 'post',
  'posts_per_page' => 5,
  'orderby'        => 'date',
  'order'          => 'DESC'
];

$query = new WP_Query($args);

if ($query->have_posts()) :
  while ($query->have_posts()) : $query->the_post(); ?>

  <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
  <p><?php the_excerpt(); ?></p>

  <?php endwhile;
  wp_reset_postdata();
endif;
?>

3. Parâmetros Comuns

Parâmetro	Função	Exemplo
post_type	Define o tipo de post.	'post', 'page', 'portfolio'
posts_per_page	Limita quantidade de resultados.	5
orderby / order	Ordena resultados.	'date' / 'DESC'
category_name	Filtra por categoria.	'noticias'
meta_key / meta_value	Filtra por metadados simples.	'destaque' / '1'
paged	Define a página atual para paginação.	get_query_var('paged')

4. Meta Queries (consultas por metadados)

As Meta Queries permitem combinar múltiplas condições baseadas em metadados armazenados na tabela wp_postmeta.

Exemplo com múltiplas condições

<?php
$args = [
  'post_type' => 'portfolio',
  'meta_query' => [
    'relation' => 'AND',
    [
      'key' => 'ativo',
      'value' => '1',
      'compare' => '='
    ],
    [
      'key' => 'ano',
      'value' => 2024,
      'compare' => '>=',
      'type' => 'NUMERIC'
    ]
  ]
];
$query = new WP_Query($args);
?>

Importante Sempre defina o tipo de dado (NUMERIC, CHAR, DATE) quando usar comparadores, para evitar falhas de comparação.

5. Tax Queries (filtrando por taxonomias)

As Tax Queries funcionam de forma semelhante, mas filtram conteúdos com base em categorias, tags ou taxonomias personalizadas.

Exemplo com tax_query

<?php
$args = [
  'post_type' => 'post',
  'tax_query' => [
    [
      'taxonomy' => 'category',
      'field' => 'slug',
      'terms' => ['design', 'ux']
    ]
  ]
];
$query = new WP_Query($args);
?>

6. Paginação

Para exibir resultados paginados, defina o parâmetro paged e use a função paginate_links() para criar os links de navegação.

Paginação básica

<?php
$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;

$args = [
  'post_type' => 'post',
  'posts_per_page' => 5,
  'paged' => $paged
];
$query = new WP_Query($args);

if ($query->have_posts()):
  while ($query->have_posts()): $query->the_post();
    the_title('<h2>', '</h2>');
  endwhile;

  echo paginate_links([
    'total' => $query->max_num_pages
  ]);

  wp_reset_postdata();
endif;
?>

7. Debug de Consultas

Durante o desenvolvimento, é útil inspecionar as queries geradas. Você pode usar o método $query->request para visualizar o SQL final.

Exibindo a query SQL

<?php
$query = new WP_Query(['post_type' => 'post']);
echo '<pre>' . $query->request . '</pre>';
?>

Dica Em ambiente local, combine com save_queries no wp-config.php para logar todas as consultas executadas.

8. Boas Práticas

Use wp_reset_postdata() após loops secundários para restaurar o contexto global.
Evite consultas pesadas dentro de loops de templates.
Prefira pre_get_posts para alterar a query principal, em vez de criar consultas duplicadas.
Cache resultados frequentes com transients.

Resultado Consultas mais rápidas, manutenção facilitada e estrutura escalável.