# 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: '!A:I', ...)` で複数列のデータ（例: `[ID, カテゴリ, タイトル, ...]` の9要素配列）を追記したのに、 read-backすると新規行はA列〜H列が空で、**最後の列（I列）にだけ**最初の要素（ID等）が入っている。 **原因（推定）**: `values.append()` はrangeで指定した範囲内で既存の「テーブル」を検出し、その最終行の直後に挿入する。 対象シートに **Basic Filter（絞り込みフィルタ）が有効**な状態だと、この「テーブル検出」ロジックが影響を受け、 新規行の列マッピングが崩れることがある（フィルタなしの別シート・別タブでは同じコードで問題なく動く＝再現条件を局所的に切り分けて確認済み）。 **回避策**: フィルタが有効なシートへの追記には `values.append()` を使わず、 1. `values.get()` で現在のデータ範囲を取得し、行数（＝次の空き行番号）を計算する 2. `values.update(range: '!A{row}:I{row}', ...)` のように**明示的な行番号を指定したupdate**で書き込む ```python 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系の数式は必ず**段階的な最小クエリでの動作確認**をセットにする。 ---