ベクトルのアップロード（upsert）

1. Upsertとは

upsert は Up load + Insert/Update の略で、ベクトル ID が存在しなければ新規挿入、存在すれば上書き という単一 API での書き込み操作です。Pinecone ではインデックス内の Namespace 単位 で upsert を行い、同一 ID の再送信は常に最新値で置き換えられますdocs.pinecone.io。

---

2. リクエスト構造と必須フィールド

json
{
  "id": "vec1",          // 文字列 ID（必須）
  "values": [0.1, …],    // ベクトル値（必須、index の dimension と一致）
  "metadata": { … }      // 任意のキー‐バリュー（フラットな JSON）
}

• ID はユニークで可読性の高い構造化 ID を推奨（例: doc123#chunk5）docs.pinecone.io

• values の長さはインデックス作成時に設定した dimension と一致していなければ 400 エラー

• metadata は 40 KB まで、ネスト不可、数値は 64-bit float へ自動変換docs.pinecone.io

---

3. Python SDK での基本例

python
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")
index = pc.Index(host="INDEX_HOST")          # Serverless の場合は host 名を指定

index.upsert(
    vectors=[
        {
            "id": "vec1",
            "values": [0.1]*1536,
            "metadata": {"genre": "comedy", "year": 2020}
        },
        {
            "id": "vec2",
            "values": [0.2]*1536,
            "metadata": {"genre": "documentary", "year": 2019}
        }
    ],
    namespace="example-namespace"
)
# => {"upsertedCount": 2}

レスポンスには正常に書き込まれたレコード数が返りますdocs.pinecone.io。

---

4. バッチアップサートとスループット最適化

• 1 リクエストあたり 最大 1,000 レコード までバッチ送信可能docs.pinecone.io

• 並列 upsert：SDK はスレッドセーフのため複数スレッド／プロセスで同時送信しても安全docs.pinecone.io

• gRPC extras を有効化すると HTTP よりも約 10–15 % 低レイテンシで転送可能docs.pinecone.io

---

5. DataFrame からの高速投入

Python SDK は upsert_from_dataframe を提供し、Parquet 由来の巨大データセットを 自動リトライ & バッチ分割 しながら投入しますdocs.pinecone.io。

---

6. Spark 連携とストリーム Upsert

Databricks／Spark 環境では公式 Spark-Pinecone コネクタ を利用し、

• Batch upsert – DataFrame.write.format("io.pinecone.spark.pinecone.Pinecone")…

• Stream upsert – writeStream.format(...).start()

で数億件規模の埋め込みを高スループットで取り込めますdocs.pinecone.io。

---

7. Integrated Embedding での upsert_text

インデックスを 埋め込みモデル統合モード で作成した場合は、事前にベクトル化せず

python
index.upsert_records(records=[{"id": "d1#c1", "chunk_text": "文章…", …}])

とテキストを直接送信すると Pinecone 側で自動ベクトル化されます（更新／import はベクトルのみ対応）docs.pinecone.io。

---

8. 主なエラーと対処

---

9. ベストプラクティスまとめ

1. 構造化 ID + 十分なメタデータ で後段のフィルタ検索やドキュメント更新を簡略化docs.pinecone.io

2. 1000 件バッチ + gRPC + 並列送信 で取り込み性能を最大化docs.pinecone.io

3. 継続的インジェストでは upsert, 一括初期ロード（1000 万件超）は import エンドポイントを選択docs.pinecone.io

4. 大規模 ETL パイプラインは Spark コネクタ や upsert_from_dataframe を活用し、再送に備えて 冪等 ID を設計docs.pinecone.iodocs.pinecone.io

---

まとめ

upsert は Pinecone への リアルタイム／インクリメンタル書き込みの中核 API です。
ID の設計、バッチサイズ、転送プロトコル、メタデータ設計を最適化することで、スケールと運用コストの両立が可能になります。