No puedo entender cómo agregar una cláusula IN en mi consulta, usando marcadores de posición.

Me gustaría que fuera algo como:

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

No puedo encontrar ninguna documentación sobre esta simple tarea. ¿Cuál es la forma correcta de lograr esto?

Te faltan los frenos.

Prueba esto:

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

Para obtener más información, consulte http://drupal.org/node/310072 , especialmente el capítulo sobre matrices de marcadores de posición:

Matrices de marcadores de posición

La capa de base de datos de Drupal incluye una característica adicional de marcadores de posición. Si el valor pasado para un marcador de posición es una matriz, se expandirá automáticamente en una lista separada por comas al igual que el marcador de posición correspondiente. Eso significa que los desarrolladores no necesitan preocuparse por contar cuántos marcadores de posición necesitarán.

Un ejemplo debería aclarar este comportamiento:

<?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 entidad:

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

Consulta SQL (select), esencialmente lo mismo para otros tipos de consulta.

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

Para Drupal 7

Ver la respuesta de Berdir.

Para Drupal 6

Puedes hacerlo así:

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

Se necesita db_placeholders en Drupal 6, que creará una cadena que contenga los marcadores de posición necesarios para la matriz de valores dados. Drupal 7 maneja todo esto internamente como lo describe Berdir.

Uso de la API de base de datos en Drupal 7

Así es como puede usar db_select () en lugar de db_query () para obtener los mismos resultados.

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

Drupal 6 Si su matriz contiene cadenas, debe decirle a db_placeholders ()

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

Actualización de Drupal 8.

También valido.

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