.. _FindDescriptor: FindDescriptor ============== Find descriptor metadata, or nearest neighbors of one input vector. Requires ``objects.read`` permission. Parameters ---------- .. include:: find_parameters.rst Without ``k_neighbors``, the command is a metadata lookup and consumes no input blob. With it, supply a positive ``k_neighbors`` (at most 2147483647), an explicit ``engine`` (Flat/IVF/HNSW/ACORN), and one finite float32 vector blob. ``with_class`` optionally selects one descriptor class. Omitting it searches compatible class indexes. Its scope always applies before top-k, even with ``knn_first: true``. See :doc:`../DescriptorIndexes` for compatibility and global top-k behavior. Additional options: * ``metric`` selects L2, IP or CS; omission selects the first common configured metric in that order. * ``knn_first`` defaults to false. True applies ordinary filters after the global top-k, potentially returning fewer matches. * ``filtered_knn`` defaults to false. True requires KNN and HNSW/ACORN and cannot combine with ``knn_first: true``. ACORN uses its filtered search when applicable. * ``with_label`` restricts stored labels; ``labels: true`` projects them. * ``distances: true`` includes ``_distance`` with KNN. * ``blobs: true`` returns stored descriptor vectors as separate output blobs; it defaults to false. .. include:: acorn_details.rst Results ------- Single-vector KNN uses ascending L2 distance or descending IP/CS score, with a stable full-identity tie order. An explicit sort replaces presentation order. Offset and limit apply after the global neighbor selection. Index results merge the snapshot's base and pending rows without returning superseded versions. Projected rows include ``_class``. Metadata lookup does not require a vector index. KNN over incompatible or populated unindexed classes fails. No matches is a successful empty result. See :doc:`../Responses` for error envelopes. .. TESTED_EXAMPLE: FindDescriptor_1 .. code-block:: json [{ "FindDescriptor": { "with_class": "party_faces", "constraints": ["$year_created", ">=", 2020], "blobs": true, "results": { "list": ["year_created", "description"] } } }] The metadata lookup above returns: .. TESTED_EXAMPLE: FindDescriptor_1_response .. code-block:: json [{ "FindDescriptor": { "blobs_start": 0, "entities": [{ "_class": "party_faces", "_blob_index": 0, "description": "friends at a party", "year_created": 2021 }], "returned": 1, "status": 0 } }] IVF nearest neighbors ~~~~~~~~~~~~~~~~~~~~~ Supply one float32 vector blob with the following query. .. TESTED_EXAMPLE: FindDescriptor_2 .. code-block:: json [{ "FindDescriptor": { "engine": "IVF", "with_class": "party_faces", "k_neighbors": 4, "blobs": true, "labels": true, "distances": true, "results": { "list": ["year_created", "description"] } } }] .. TESTED_EXAMPLE: FindDescriptor_2_response .. code-block:: json [{ "FindDescriptor": { "blobs_start": 0, "entities": [{ "_class": "party_faces", "_blob_index": 0, "_distance": 1.0, "_label": "Chaleb Zhen", "description": "Picture of Chaleb Zhen", "year_created": 2023 }, { "_class": "party_faces", "_blob_index": 1, "_distance": 1.0, "_label": "Emili Donna", "description": "Picture of Emili Donna", "year_created": 2023 }, { "_class": "party_faces", "_blob_index": 2, "_distance": 2.0, "_label": "Swarna Sonia", "description": "Picture of Swarna Sonia", "year_created": 2023 }, { "_class": "party_faces", "_blob_index": 3, "_distance": 2.0, "_label": "El Swarna", "description": "Picture of El Swarna", "year_created": 2023 }], "returned": 4, "status": 0 } }] HNSW nearest neighbors ~~~~~~~~~~~~~~~~~~~~~~ Supply one float32 vector blob with the following query. .. TESTED_EXAMPLE: FindDescriptor_3 .. code-block:: json [{ "FindDescriptor": { "with_class": "party_faces", "k_neighbors": 4, "engine": "HNSW", "blobs": true, "labels": true, "distances": true, "results": { "list": ["year_created", "description"] } } }] .. TESTED_EXAMPLE: FindDescriptor_3_response .. code-block:: json [{ "FindDescriptor": { "blobs_start": 0, "entities": [{ "_class": "party_faces", "_blob_index": 0, "_distance": 36.0, "_label": "Harisha Balaram", "description": "Picture of Harisha Balaram", "year_created": 2023 }, { "_class": "party_faces", "_blob_index": 1, "_distance": 49.0, "_label": "Liidia Bertha", "description": "Picture of Liidia Bertha", "year_created": 2023 }, { "_class": "party_faces", "_blob_index": 2, "_distance": 64.0, "_label": "Emili Donna", "description": "Picture of Emili Donna", "year_created": 2023 }, { "_class": "party_faces", "_blob_index": 3, "_distance": 81.0, "_label": "Jockel Cecilie", "description": "Picture of Jockel Cecilie", "year_created": 2023 }], "returned": 4, "status": 0 } }]