WordPressの $wpdb で直接SQLを書く — プレースホルダは4種類あり、引用符で囲んではいけない

公開 2026-10-25 ／ 更新 2026-10-25 ／ 文：ランツ

先に結論

$wpdb->prepare() のプレースホルダを %s と %d の2つだと思っているなら、 情報が2023年より前のものです。いまは4種類あります。

そして、書き方に強い決まりがあります。

'%s' のようにシングルクォートで囲む書き方は間違いです。 prepare() が自分で引用符を付けるので、二重に囲むことになります。

そもそも $wpdb を使うべきか

最初に確認してください。 投稿やユーザーを扱いたいだけなら、SQLを書かずに済むことがほとんどです。

上5行を $wpdb でやると損をします。 キャッシュもフックも効かなくなり、プラグインとの相性も悪くなります。 $wpdb が本領を出すのは、下3行のような「標準APIでは書けないクエリ」です。

使うときは、グローバルの $wpdb を受け取ります。公式も、自分で new しないよう書いています。

function my_count_published() {
    global $wpdb;                       // 公式：new wpdb せず、グローバルを使う
    return (int) $wpdb->get_var(
        "SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_status = 'publish'"
    );
}

prepare() の書き方

プレースホルダは4種類ある

%f と %i を書いている解説はほとんどありません。 公式リファレンスには4つとも載っています（表1）。

global $wpdb;

$sql = $wpdb->prepare(
    "SELECT * FROM {$wpdb->postmeta}
     WHERE post_id = %d
       AND meta_key = %s
       AND meta_value > %f",
    $post_id, $key, $threshold
);
$rows = $wpdb->get_results( $sql );

prepare() は文字列を返すだけです。 実行はしません。返ってきたSQLを get_results() などに渡します。

引用符で囲んではいけない

ここが一番間違えられています。 公式リファレンスの表現は強く、「MUST（しなければならない）」が使われています。

部分一致は、エスケープ用の関数と組み合わせます。

global $wpdb;

// % と _ をエスケープしてから、前後に % を付ける
$like = '%' . $wpdb->esc_like( $keyword ) . '%';

$sql = $wpdb->prepare(
    "SELECT * FROM {$wpdb->posts} WHERE post_title LIKE %s",
    $like                      // ← プレースホルダは囲まない
);

esc_like() を忘れると、利用者が入力した % がワイルドカードとして効きます。 検索語に % を入れただけで全件返る、という挙動になります。

テーブル名を渡せるようになった

WordPress 6.2 で %i が追加されました。 公式のChangelogにこう書かれています。

それ以前は、テーブル名やカラム名を変数で渡す安全な方法がありませんでした。 だから古い記事はテーブル名を文字列に直接埋め込んでいます。 固定の文字列なら問題ありませんが、外から来る値だと危険でした。

global $wpdb;

// 6.2 以降：カラム名も安全に渡せる
$sql = $wpdb->prepare(
    "SELECT * FROM %i ORDER BY %i DESC LIMIT %d",
    $wpdb->posts, $order_column, $limit
);

// 対応しているか確認してから使う
if ( $wpdb->has_cap( 'identifier_placeholders' ) ) {
    // %i が使える
}

型が合わないと値が変わる

%d に文字列を渡してもエラーにはなりません。 変換されて別の値になります。公式リファレンスが具体例を載せています。

取得メソッドの使い分け

欲しい形に合わせて選びます。どれも同じSQLを渡せますが、返ってくる形が違います。

get_var() を使うべき場面で get_results() を使うのは、よくある遠回りです。 件数が欲しいだけなら、配列を受け取って1つ目の要素を取り出す必要はありません。

global $wpdb;

// 件数：get_var
$count = (int) $wpdb->get_var(
    $wpdb->prepare( "SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_type = %s", $type )
);

// IDの一覧：get_col
$ids = $wpdb->get_col(
    $wpdb->prepare( "SELECT ID FROM {$wpdb->posts} WHERE post_status = %s", 'publish' )
);

// 1行：get_row
$row = $wpdb->get_row(
    $wpdb->prepare( "SELECT * FROM {$wpdb->posts} WHERE ID = %d", $id )
);

書き込み系メソッド

書き込みは、SQLを書かずに済む方法があります。 insert() / update() / delete() は、配列で渡せばエスケープもやってくれます。

global $wpdb;

// 配列で渡せば、SQLもエスケープも書かなくてよい
$wpdb->insert(
    $wpdb->prefix . 'my_table',
    array( 'post_id' => $post_id, 'score' => $score ),   // データ
    array( '%d', '%f' )                                   // 書式（省略可だが明示する）
);

$new_id = $wpdb->insert_id;   // 追加された行のID

第3引数の書式は省略できますが、書いてください。 省略するとすべて %s として扱われ、数値カラムに文字列が入ります。

テーブル名の組み立て

WordPressのテーブル名には接頭辞が付きます。 既定は wp_ ですが、変えられるのでハードコードしてはいけません。

最後の2つの違いは、マルチサイトで効いてきます。 prefix はサイトごとに wp_2_ のような形になりますが、 base_prefix は wp_ のままです。 サイトごとに分けたいデータは prefix、全体で共有するなら base_prefix です。

詰まったときに見るもの

$wpdb は失敗しても例外を投げません。 false や空配列が返るだけなので、原因を自分で取りに行きます。

1行目を先に見てください。 last_query にはプレースホルダが置き換わったあとのSQLが入っています。 %d に文字列を渡して 0 になっていれば、ここで見えます（表6）。

global $wpdb;

$rows = $wpdb->get_results( $sql );

if ( $wpdb->last_error ) {
    error_log( 'SQL: ' . $wpdb->last_query );
    error_log( 'ERR: ' . $wpdb->last_error );
}

AIに任せるときの注意

判定の目安です。出てきたコードに '%s'（引用符つき）があったら、情報が古いと思ってください。 %i が使われていれば、6.2以降を知っています。

よくある質問

プレースホルダは引用符で囲むのですか

囲みません。公式が「すべてのプレースホルダは引用符で囲まないままにしなければならない」と書いています（表4）。 prepare() が自分で付けるので、囲むと二重になります。

%i とは何ですか

テーブル名やカラム名のためのプレースホルダです。 WordPress 6.2 で追加されました（公式Changelog）。 それ以前は、識別子を安全に渡す方法がありませんでした。

%d に文字列を渡すとどうなりますか

エラーにならず 0 になります（表6）。 「0件返る」「IDが0のレコードを探している」という症状の原因は、だいたいこれです。

LIKE検索はどう書きますか

esc_like() でエスケープしてから前後に % を付け、 プレースホルダ自体は囲みません（詳しく）。 esc_like() を忘れると、入力された % がワイルドカードとして効きます。

insert() でも prepare() は必要ですか

不要です。insert() / update() / delete() / replace() は 配列で渡せばエスケープされます（表8）。 query() だけは必要です。

テーブル名はハードコードしていいですか

いけません。接頭辞は変更できます。 $wpdb->posts のようなプロパティか、自作テーブルなら $wpdb->prefix を使ってください（表9）。

エラーが出ずに0件返ります

$wpdb->last_query を見てください（表10）。 プレースホルダが展開されたあとのSQLが入っています。 $wpdb は失敗しても例外を投げないので、自分で取りに行く必要があります。

WP_Query と $wpdb、どちらを使うべきですか

投稿やユーザーを扱うなら WP_Query です（表3）。 $wpdb が要るのは、自作テーブルと、標準APIでは書けない集計クエリです。

まとめ

• プレースホルダは4種類。%d %s %f と、6.2で追加された %i。
• プレースホルダを引用符で囲まない。公式が「MUST」で書いている。'%s' は間違い。
• %i でテーブル名・カラム名を安全に渡せる。対応は has_cap('identifier_placeholders') で確認。
• %d に文字列を渡すとエラーにならず 0 になる。0件返る症状の典型。
• LIKEは esc_like() を通す。忘れると入力の % がワイルドカードになる。
• 取得は形で選ぶ。件数なら get_var()、1列なら get_col()。
• insert() 系に prepare() は不要。必要なのは query() だけ。
• 書式の第3引数は省略せずに書く。省略すると全部 %s になる。
• テーブル名はハードコードしない。マルチサイトでは prefix と base_prefix を使い分ける。
• 失敗しても例外は出ない。詰まったら last_query → last_error の順に見る。
• そもそも WP_Query で足りないか先に確認する。投稿を扱うだけなら SQL は要らない。