Não consigo descobrir como adicionar uma cláusula IN na minha consulta, usando espaços reservados.

Eu gostaria que fosse algo como:

$nids = array(1, 2, 3);
$result = db_query('SELECT * FROM {node} WHERE nid IN :nids', array(':nids' => $nids));

Não foi possível encontrar nenhuma documentação sobre esta tarefa simples. Qual é a maneira correta de conseguir isso?

Está faltando o aparelho.

Tente o seguinte:

$nids = array(1, 2, 3);
$result = db_query('SELECT * FROM {node} WHERE nid IN (:nids)', array(':nids' => $nids));

Para obter mais informações, consulte http://drupal.org/node/310072 , especialmente o capítulo sobre matrizes de espaço reservado:

Matrizes de espaço reservado

A camada de banco de dados do Drupal inclui um recurso extra de espaços reservados. Se o valor passado para um espaço reservado for uma matriz, ele será automaticamente expandido para uma lista separada por vírgula, assim como o espaço reservado correspondente. Isso significa que os desenvolvedores não precisam se preocupar em contar quantos espaços reservados serão necessários.

Um exemplo deve tornar esse comportamento mais claro:

<?php
// This code:
db_query("SELECT * FROM {node} WHERE nid IN (:nids)", array(':nids' => array(13, 42, 144));

// Will get turned into this prepared statement equivalent automatically:
db_query("SELECT * FROM {node} WHERE nid IN (:nids_1, :nids_2, :nids_3)", array(
  ':nids_1' => 13, 
  ':nids_2' => 42, 
  ':nids_3' => 144,
));

// Which is equivalent to the following literal query:
db_query("SELECT * FROM {node} WHERE nid IN (13, 42, 144)");
?>

Para Drupal 8

Consulta de entidade:

$query = \Drupal::entityTypeManager()->getStorage('entity_type')->getQuery();
$query->condition('field/property', [1, 2, 3], 'IN');
$ids = $query->execute();

Consulta SQL (selecione), essencialmente o mesmo para outros tipos de consulta.

$query = \Drupal::database()->select('table', 't');
$query->condition('column', [1, 2, 3], 'IN');
...

Para Drupal 7

Veja a resposta de Berdir.

Para Drupal 6

Você pode fazer assim:

$nids = array(1, 2, 3);
$placeholders = db_placeholders($nids);
$result = db_query("SELECT * FROM {node} WHERE nid IN ($placeholders)", $nids);

db_placeholders é necessário no Drupal 6, que criará uma string que contém os espaços reservados necessários para a matriz de valores fornecida. O Drupal 7 lida com tudo isso internamente, como Berdir descreve.

Usando a API do banco de dados no Drupal 7

Veja como você pode usar db_select () em vez de db_query () para os mesmos resultados.

$nids = array(1, 2, 3);
$query = db_select('node', 'n')
  ->fields('n')
  ->condition('n.nid', $nids, 'IN')
  ->execute();
$nodes = $query->fetchAll();

Drupal 6 Se sua matriz contiver strings, você precisará informar db_placeholders ()

$colours = array('red', 'yellow', 'blue');
$placeholders = db_placeholders($colours,'text');
$result = db_query("SELECT * FROM {bricks} WHERE colour IN ($placeholders)", $colours);

Atualização do Drupal 8.

Também válido.

$nids = db_query("SELECT nid FROM node_field_data WHERE nid IN (:nids[]) AND status = 1", [
  ':nids[]' => $nids
])->fetchCol();