エラーと対処例（例：アップサート失敗、フィルター無効など）

1. はじめに

Pinecone API では HTTP ステータスコード と SDK 例外 を併用して失敗を通知します。まずはエラーを分類し、典型的な原因と対処フローを把握することが重要です。以下では 「アップサート失敗」 と 「フィルターが効かない」 を中心に、代表的なエラーとベストプラクティスを整理します。

2. 共通エラーコード早見表

ステータス	原因の代表例	重点チェックポイント
400 INVALID_ARGUMENT	ベクトル次元不一致・無効なフィルター	index.dimension と `len(values)`、フィルター構文
401 UNAUTHENTICATED	API キー漏れ／誤り	`pinecone.init()` のキー・環境変数
403 FORBIDDEN（QUOTA_EXCEEDED など）	プラン／クォータ超過、削除保護	Starter 上限、ストレージ 2 GB 制限など
404 NOT_FOUND	インデックス・名前空間・ID 不存在	名前空間名・ID・リージョン
409 ALREADY_EXISTS	ID 重複・リソース重複	Upsert 前に `delete` or `update`
412 FAILED_PRECONDITIONS	前提条件未充足	バックアップ中の更新など
422 UNPROCESSABLE_ENTITY	JSON スキーマ違反	配列要素型・Null 値
429 TOO_MANY_REQUESTS	レート／ユニット上限超過	読み書きユニット、50 MB/s Upsert 制限
5xx 系	Pinecone 側障害	エラー文面を添えて再試行／サポート連絡

docs.pinecone.iodocs.pinecone.io

3. アップサート失敗の代表パターンと対処

症状	原因	解決手順
dimension mismatch : 400 エラー／`ResponseError: dimension does not match`	ベクトル長が index.dimension と不一致	1) index 作成時の `dimension` を確認 2) `assert len(vec)==index.dimension` で事前検証
ID 重複による 409	同じ ID を複数回 upsert	`on_error="continue"` でスキップ、または `delete` 後に upsert
Starter で upsert 成功なのに反映されない	非同期反映 + Starter プランのレイテンシ	① `describe_index_stats()` で件数確認 ② 数分待機 ③ 即時反映が必要なら Standard 以上へ
429 TOO_MANY_REQUESTS	月間 Write Unit／秒間 50 MB 制限超過	① SDK の自動リトライ (`max_retries`, backoff) を有効化 ② バッチサイズを調整 ③ プランアップグレード
403 QUOTA_EXCEEDED – 2 GB storage	Starter の総ストレージ上限	古いレコードを `delete` するか上位プランへ

コード断片（Python SDK v7 系）

python
from pinecone import Pinecone, PineconeException
import backoff, time, os

pc = Pinecone(api_key=os.getenv("PINECONE_API_KEY"))
index = pc.Index("my-index")

@backoff.on_exception(backoff.expo,
                      PineconeException,
                      max_time=60,
                      giveup=lambda e: e.status_code < 500)
def safe_upsert(vectors, namespace=""):
    index.upsert(vectors=vectors, namespace=namespace)

# 事前バリデーション
dim = index.describe_index_stats()['dimension']
for _id, values, meta in vectors:
    if len(values) != dim:
        raise ValueError("Dimension mismatch")
safe_upsert(vectors)

4. フィルターが効かない／結果が空 ([]) のとき

症状	主要原因	確認 & 修正ポイント
クエリに filter を付けると 0 件になる	① `metadata_config` を誤指定 – メタデータがインデックス化されていない	新規 index 作成時に `metadata_config` を削除 or 正しいスキーマにして再作成
400 INVALID_ARGUMENT – “$eq expects string”	② フィルター構文誤り – `$eq` に配列を渡す等	`$eq: "documentary"` のようにスカラーを渡す
結果が常に空	③ キー名／大文字小文字ミスマッチ	Upsert 時と同じキー名を厳密一致で指定
422 UNPROCESSABLE_ENTITY	④ Null 値・型不一致	Null を除去、型（数値/文字列）を合わせる
複数条件 `$in` `$and` が効かない	⑤ 変数に空配列が混在	送信前に `if value:` で空チェック

フィルター例（複数条件）

python
filter = {
    "genre":   {"$eq": "documentary"},
    "year":    {"$gte": 2019},
    "$and": [
        {"rating": {"$gte": 4.0}},
        {"lang":   {"$in": ["ja", "en"]}}
    ]
}
res = index.query(vector=q, top_k=5, filter=filter)

5. ベストプラクティス・再発防止策

スキーマ管理
- インデックス作成時に dimension, metric, metadata_config を必ず一元管理し、CI で定数化。
- 変更が必要な場合は 新しいインデックスを作成 → 再インポート → エイリアス切替 を推奨。
入力検証レイヤー
- Upsert 直前に dimension、NaN、Inf、Null metadata をチェック。
- フィルターを生成するユーティリティでキー名・型を統一。
レートリミット耐性
- SDK v7 以降の backoff_strategy="exponential" オプション、または外部ライブラリで 429 を自動再試行。
- 書き込みバッチ: 500 ～ 5 000 件程度／50 MB 未満を目安、2 倍指数バックオフ。
監視とアラート
- describe_index_stats() のレコード数を CloudWatch / Grafana で定期取得。
- Dashboard の Starter Usage や Rate Limit グラフを上限 80 % でアラート。 docs.pinecone.io
ログ出力の標準化
- 例外メッセージだけでなく status_code, error_type, context を構造化ログに残す。
- 失敗レコードを一時キュー（SQS など）へ退避し、後続バッチで再実行。

6. まとめ

アップサート失敗 は次元不一致とクォータ超過が最多。事前バリデーションとレート制御で予防できます。
フィルター無効 は metadata_config と構文ミスが主因。インデックス作成時の設定とキー名の一致を必ず確認してください。
Pinecone API は HTTP ステータスと詳細メッセージを返すので、例外メッセージ全文を必ずログに残し、再試行ポリシーを組み込む ことが安定運用の鍵です。

ChatGPT4o 生成日：2025/06/20