Google Sheets API 落とし穴2つ（values.append列ズレ / QUERY ORDER BY silent fail）

Google Sheets API (v4, Python/Node/Apps Script共通の概念) でスプレッドシートに読み書きする自動化を作るときに、 無言で壊れる2つの罠と回避策。どちらもエラーは出ず、read-back検証をして初めて発覚する。

罠1: 対象シートに「フィルタ（Basic Filter）」が有効だと values.append() で列がズレる

症状: spreadsheets.values.append(range: '<Sheet>!A:I', ...) で複数列のデータ（例: [ID, カテゴリ, タイトル, ...] の9要素配列）を追記したのに、 read-backすると新規行はA列〜H列が空で、最後の列（I列）にだけ最初の要素（ID等）が入っている。

原因（推定）: values.append() はrangeで指定した範囲内で既存の「テーブル」を検出し、その最終行の直後に挿入する。 対象シートに Basic Filter（絞り込みフィルタ）が有効な状態だと、この「テーブル検出」ロジックが影響を受け、 新規行の列マッピングが崩れることがある（フィルタなしの別シート・別タブでは同じコードで問題なく動く＝再現条件を局所的に切り分けて確認済み）。

回避策: フィルタが有効なシートへの追記には values.append() を使わず、

1. values.get() で現在のデータ範囲を取得し、行数（＝次の空き行番号）を計算する
2. values.update(range: '<Sheet>!A{row}:I{row}', ...) のように明示的な行番号を指定したupdateで書き込む

res = service.spreadsheets().values().get(spreadsheetId=sid, range='Sheet1!A:I').execute()
next_row = len(res.get('values', [])) + 1
service.spreadsheets().values().update(
    spreadsheetId=sid, range=f'Sheet1!A{next_row}:I{next_row}',
    valueInputOption='USER_ENTERED', body={'values': [row]}
).execute()

検証を必ず入れる: 書き込み後に同じ範囲を values.get() で読み戻し、A列（先頭列）に期待した値が入っているかをassertする。 append()は例外を投げずに成功ステータスを返すため、戻り値だけでは列ズレに気づけない。

罠2: QUERY() の ORDER BY が、列の値の型が混在していると全行を silent fail させる

症状: =QUERY(範囲, "select A,B,C where カテゴリ列 <> 'X' order by 日付列 asc", 1) のようなクエリが、 order by を付けているとヘッダー行だけ表示され、データ行が0件になる（エラー表示すら出ない）。 同じ select ... where ... 部分だけを order by 無しで実行すると、データはちゃんと返る。

原因: order by の対象列に、日付型のセルと、空文字列・文字列（日付でない値）が混在していると、 QUERY言語の内部ソート処理が型の不一致で失敗し、結果セット全体を黙って空にする。 （where句のフィルタ自体は正しく機能しているのに、order byを追加した瞬間だけ0行になる、という切り分けで発見）

回避策:

• 対象列の型を統一できないなら、その order by 句を諦めて外す（表示順は呼び出し側や別ロジックでソートする）
• どうしても順序が欲しいなら、order by 対象列を別途IF/日付変換で正規化してから使う
• デバッグ手順: order by を外した最小クエリでデータが返ることを先に確認 → order by を1列ずつ足して、どの列で0件になるか切り分ける

教訓（両方に共通）

Sheets API / QUERY関数は「エラーを返さず、意図しない結果を黙って返す」失敗モードが多い。 書き込み系操作は必ずread-back検証、QUERY系の数式は必ず段階的な最小クエリでの動作確認をセットにする。