Qdrant ベクターデータ（ポイント）

ポイント

ポイントはQdrantによって操作される中心的なエンティティです。ポイントはベクトルとオプションのペイロードで構成されるレコードです。

ベクトルの類似性に基づいてコレクション内にグループ化されたポイントを検索できます。プロセスの詳細な説明は、検索とフィルターのセクションで提供されています。

このセクションでは、ベクトルの作成と管理方法について紹介します。

ポイントの変更操作は非同期であり、2つのステップに分かれています。最初の段階では、操作は先行ログに書き込まれます。

この時点で、たとえマシンの電源が切れても、サービスはデータを失いません。

ヒント：Qdrantでは、ポイントは抽象的な概念です。それらは、MySQLテーブルのデータの行と考えることができます。

結果の待ち時間

APIが&wait=falseパラメータで呼び出された場合、または明示的に指定されていない場合、クライアントはデータ受信の確認メッセージを受け取ります。

{
    "result": {
        "operation_id": 123,
        "status": "acknowledged"
    },
    "status": "ok",
    "time": 0.000206061
}

この応答では、データの直ちの取得を保証するものではありません。これは最終的に整合性が保たれる形式を利用しています。コレクションの実際の更新プロセス中には時間がかかる場合があります。実際にはこのリクエストは最終的に失敗することがあります。大量のベクトルを挿入する場合は、パイプライン操作を十分に利用するために非同期リクエストの使用をお勧めします。

API応答後に検索の直ちの利用が必要な場合は、?wait=trueフラグを使用します。この場合、APIは操作が完了した後にのみ結果を返します。

{
    "result": {
        "operation_id": 0,
        "status": "completed"
    },
    "status": "ok",
    "time": 0.000206061
}

ポイントID

Qdrantは、ポイントの識別子として64ビットの符号なし整数およびUUIDをサポートしています。

UUID文字列表現の例は以下の通りです。

• 単純な表現：936DA01F9ABD4d9d80C702AF85C822A8
• ハイフン付き表現：550e8400-e29b-41d4-a716-446655440000
• URN：urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4

つまり、各リクエストで数値IDの代わりにUUID文字列を使用できます。例えば：

PUT /collections/{collection_name}/points

{
    "points": [
        {
            "id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
            "payload": {"color": "red"},
            "vector": [0.9, 0.1, 0.1]
        }
    ]
}

および

PUT /collections/{collection_name}/points

{
    "points": [
        {
            "id": 1,
            "payload": {"color": "red"},
            "vector": [0.9, 0.1, 0.1]
        }
    ]
}

の両方が有効です。

データポイントのアップロード

パフォーマンスを最適化するために、Qdrantはデータポイントの一括ロードをサポートしています。つまり、複数のデータポイントを1つのAPI呼び出しでサービスにロードすることができます。一括ロードにより、ネットワーク接続のオーバーヘッドを大幅に削減することができます。

Qdrant APIは、レコード指向と列指向の2つの一括作成方法をサポートしています。内部的には、これらのオプションは区別がつかず、単に相互作用の便宜のためのものです。

REST APIを使用してデータポイントを作成する方法:

PUT /collections/{collection_name}/points

{
    "batch": {
        "ids": [1, 2, 3],
        "payloads": [
            {"color": "red"},
            {"color": "green"},
            {"color": "blue"}
        ],
        "vectors": [
            [0.9, 0.1, 0.1],
            [0.1, 0.9, 0.1],
            [0.1, 0.1, 0.9]
        ]
    }
}

または、レコード指向のアプローチを使用した同等なメソッド:

PUT /collections/{collection_name}/points

{
    "points": [
        {
            "id": 1,
            "payload": {"color": "red"},
            "vector": [0.9, 0.1, 0.1]
        },
        {
            "id": 2,
            "payload": {"color": "green"},
            "vector": [0.1, 0.9, 0.1]
        },
        {
            "id": 3,
            "payload": {"color": "blue"},
            "vector": [0.1, 0.1, 0.9]
        }
    ]
}

QdrantのすべてのAPI、データポイントのロードを含めて冪等です。つまり、同じ方法を連続して実行することは、単一の実行と同等です。

この場合、同じIDを持つデータポイントを再度アップロードすると、既存のデータポイントは上書きされます。

冪等性は、正確な一度限りの保証を提供しないメッセージキューを使用する場合に便利です。この場合でも、Qdrantはデータの整合性を確保します。

バージョン0.10.0から利用可能

作成するコレクションに複数のベクトルがある場合、ベクトルごとにデータを指定することができます:

PUT /collections/{collection_name}/points

{
    "points": [
        {
            "id": 1,
            "vector": {
                "image": [0.9, 0.1, 0.1, 0.2],
                "text": [0.4, 0.7, 0.1, 0.8, 0.1, 0.1, 0.9, 0.2]
            }
        },
        {
            "id": 2,
            "vector": {
                "image": [0.2, 0.1, 0.3, 0.9],
                "text": [0.5, 0.2, 0.7, 0.4, 0.7, 0.2, 0.3, 0.9]
            }
        }
    ]
}

バージョン1.2.0から利用可能

名前付きベクトルは任意です。データポイントをアップロードする際、一部のベクトルを省略することができます。たとえば、image ベクトルだけを持つデータポイントと text ベクトルだけを持つ別のデータポイントをアップロードすることができます。

既存のIDを持つデータポイントを変更する場合、既存のデータポイントがまず削除され、その後指定されたベクトルで再挿入されます。言い換えると、すべてのデータポイントが置換され、指定されていないベクトルはnullに設定されます。既存のベクトルを変更せずに指定されたベクトルのみを更新したい場合は、ベクトルの更新を参照してください。

データポイントの修正

データポイントを修正するには、そのベクトルやペイロードを修正することができます。これを実現するためのいくつかの方法があります。

ベクトルの更新

バージョンv1.2.0から利用可能

このメソッドは指定されたポイントのベクトルを更新します。指定されていないベクトルは変更されません。すべての指定されたポイントは存在する必要があります。

REST API（スキーマ）:

PUT /collections/{collection_name}/points/vectors

{
    "points": [
        {
            "id": 1,
            "vector": {
                "image": [0.1, 0.2, 0.3, 0.4]
            }
        },
        {
            "id": 2,
            "vector": {
                "text": [0.9, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2]
            }
        }
    ]
}

ポイントを更新してすべてのベクトルを置き換える場合は、アップロードポイント操作を参照してください。

ベクトルの削除

バージョンv1.2.0から利用可能

このメソッドは指定されたポイントからのみベクトルを削除します。他のベクトルは変更されません。ポイントは削除されません。

REST API（スキーマ）:

POST /collections/{collection_name}/points/vectors/delete

{
    "points": [0, 3, 100],
    "vectors": ["text", "image"]
}

ペイロードの設定

指定されたポイントにペイロード値を設定します。

REST API（スキーマ）:

POST /collections/{collection_name}/points/payload

{
    "payload": {
        "property1": "string",
        "property2": "string"
    },
    "points": [
        0, 3, 100
    ]
}

変更するポイントのIDを知る必要はありません。フィルターを使用する別の方法もあります。

POST /collections/{collection_name}/points/payload

{
    "payload": {
        "property1": "string",
        "property2": "string"
    },
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    }
}

ペイロードの上書き

指定されたペイロードで既存のペイロードを完全に置き換えます。

REST API（スキーマ）:

PUT /collections/{collection_name}/points/payload

{
    "payload": {
        "property1": "string",
        "property2": "string"
    },
    "points": [
        0, 3, 100
    ]
}

ペイロードの設定と同様に、変更するポイントのIDを知る必要はありません。フィルターを使用する別の方法もあります。

ペイロードキーの削除

REST API（スキーマ）:

POST /collections/{collection_name}/points/payload/delete

{
    "keys": ["color", "price"],
    "points": [0, 3, 100]
}

また、フィルターを使用してポイントからペイロードキーを削除することもできます。

POST /collections/{collection_name}/points/payload/delete

{
    "keys": ["color", "price"],
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    }
}

ペイロードのクリア

このメソッドは、指定されたポイントからすべてのペイロードキーを削除します。

REST API（スキーマ）:

POST /collections/{collection_name}/points/payload/clear

{
    "points": [0, 3, 100]
}

ポイントの削除

REST API（スキーマ）：

POST /collections/{collection_name}/points/delete

{
    "points": [0, 3, 100]
}

ポイントを削除する別の方法は、フィルターを使用してポイントを指定することです：

POST /collections/{collection_name}/points/delete

{
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    }
}

この例では、コレクションから { "color": "red" } を持つすべてのポイントを削除します。

ポイントの取得

IDによってポイントを取得するメソッド：

REST API（スキーマ）：

POST /collections/{collection_name}/points

{
    "ids": [0, 3, 100]
}

このメソッドには、with_vectors と with_payload という追加のパラメータがあります。これらのパラメータを使用すると、必要なポイントの結果部分を選択できます。除外することで、無駄なデータ転送を避けることができます。

また、APIを介して単一のポイントを取得することも可能です：

REST API（スキーマ）：

GET /collections/{collection_name}/points/{point_id}

スクロール

時には、IDを知らないまますべての保存されたポイントを取得するか、フィルタリング条件を満たすポイントを反復処理する必要があります。

REST API（スキーマ）：

POST /collections/{collection_name}/points/scroll

{
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    },
    "limit": 1,
    "with_payload": true,
    "with_vector": false
}

color=red に一致するすべてのポイントを返します：

{
    "result": {
        "next_page_offset": 1,
        "points": [
            {
                "id": 0,
                "payload": {
                    "color": "red"
                }
            }
        ]
    },
    "status": "ok",
    "time": 0.0001
}

スクロールAPIは、フィルターと一致するすべてのポイントをページネーションの形式で返します。

すべての結果ポイントはIDでソートされます。次のページをクエリするには、offset フィールドに最大で見つかったIDを指定する必要があります。便宜上、このIDは next_page_offset フィールドにも返されます。next_page_offset フィールドの値が null の場合、最後のページに到達したことを意味します。

ポイントの数え上げ

バージョンv0.8.4から利用可能

時には、実際に検索を行わずにフィルタリング条件に一致するポイントの数を知るだけで十分です。

例えば、以下のようなシナリオで役立ちます：

• ファセット検索の結果サイズの見積もり
• ページネーションのためのページ数の決定
• クエリ実行速度のデバッグ

REST API（スキーマ）：

POST /collections/{collection_name}/points/count

{
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    },
    "exact": true
}

指定したフィルタリング条件に一致するポイントの数を返します：

{
    "count": 3811
}

一括更新

v1.5.0以降で利用可能

複数のポイントに対して一括操作を実行できます。これには、ポイント、ベクトル、ペイロードの挿入、更新、削除が含まれます。

一括更新リクエストは、順次実行される一連の操作で構成されます。一括処理できる操作には次のものがあります：

• ポイントの挿入または更新：upsertまたはUpsertOperation
• ポイントの削除：delete_pointsまたはDeleteOperation
• ベクトルの更新：update_vectorsまたはUpdateVectorsOperation
• ベクトルの削除：delete_vectorsまたはDeleteVectorsOperation
• ペイロードの設定：set_payloadまたはSetPayloadOperation
• ペイロードの上書き：overwrite_payloadまたはOverwritePayload
• ペイロードの削除：delete_payloadまたはDeletePayloadOperation
• ペイロードのクリア：clear_payloadまたはClearPayloadOperation

以下のコード例はすべての操作を使用しています。

REST API (Schema)：

POST /collections/{collection_name}/points/batch

{
    "operations": [
        {
            "upsert": {
                "points": [
                    {
                        "id": 1,
                        "vector": [1.0, 2.0, 3.0, 4.0],
                        "payload": {}
                    }
                ]
            }
        },
        {
            "update_vectors": {
                "points": [
                    {
                        "id": 1,
                        "vector": [1.0, 2.0, 3.0, 4.0]
                    }
                ]
            }
        },
        {
            "delete_vectors": {
                "points": [1],
                "vector": [""]
            }
        },
        {
            "overwrite_payload": {
                "payload": {
                    "test_payload": "1"
                },
                "points": [1]
            }
        },
        {
            "set_payload": {
                "payload": {
                    "test_payload_2": "2",
                    "test_payload_3": "3"
                },
                "points": [1]
            }
        },
        {
            "delete_payload": {
                "keys": ["test_payload_2"],
                "points": [1]
            }
        },
        {
            "clear_payload": {
                "points": [1]
            }
        },
        {"delete": {"points": [1]}}
    ]
}

単一の種類の操作で一括ポイントを使用するには、その操作内で直接一括処理機能を使用します。