search

Search a collection with near-vector

Performs a similarity search over the objects of a collection, anchored at a vector supplied by the caller: the query vector is searched against the vector index and the closest objects are returned, each as an envelope of its id, the selected properties, the selected references and, when requested, its retrieval metadata. No query is vectorized, so collections without a vectorizer module are fully searchable. The query vector must have the dimensionality of the vector space it is searched against, that is of the collection's (target) vector. A vector of the wrong dimensionality is rejected with 422 by uncompressed HNSW and flat indexes; a BQ- or RQ-compressed HNSW index does not detect it and yields an empty result set instead.

post/search/{collection}/near-vector

Request

  • Base URL: https://localhost:8080/v1
  • URL: https://localhost:8080/v1/search/{collection}/near-vector
  • Auth: one of:
    • none
    • OAuth 2 (implicit, authorization URL http://to-be-configured-in-the-application-config)

Path parameters

collectionstring required

The name (or alias) of the collection to search. A lowercase first letter is normalized to the canonical uppercase form.

Request body

limitinteger nullable

The maximum number of objects to return. Omitted or 0 falls back to the server default (QUERY_DEFAULTS_LIMIT); a value above QUERY_MAXIMUM_RESULTS is rejected.

offsetinteger nullable

The number of objects to skip before returning results. Used with limit for pagination.

autoLimitinteger nullable

Cut results off at the first steep drop in score (autocut). The value is the number of score jumps to allow before cutting.

returnPropertiesstring[]

The non-reference properties to return. Omitted returns all non-reference, non-blob properties; an empty array returns no properties. References are selected with returnReferences.

returnMetadatastring[]

The retrieval metadata to return under each result's metadata key. The object id is always returned as each result's id field. Omitted or empty returns no metadata block.

tenantstring

The tenant to search in a multi-tenant collection.

consistencyLevel'ONE' | 'QUORUM' | 'ALL'

The consistency level for the read.

singlePromptstring nullable

Reserved for per-object retrieval-augmented generation. Returns 422 (not yet supported).

groupedTaskstring nullable

Reserved for grouped retrieval-augmented generation. Returns 422 (not yet supported).

groupBystring nullable

Reserved for grouped search. Returns 422 (not yet supported).

numberOfGroupsinteger nullable

Reserved for grouped search. Returns 422 (not yet supported).

objectsPerGroupinteger nullable

Reserved for grouped search. Returns 422 (not yet supported).

vectorunknown required
certaintynumber nullable

Minimum normalized certainty of a match. Only for cosine-distance vector indexes. Mutually exclusive with distance.

distancenumber nullable

Maximum vector distance of a match. Mutually exclusive with certainty.

targetVectorstring

The named vector to search (the query vector is compared against the vectors stored under this name, and must match their dimensionality). Required when the collection has more than one named vector.

Example request

{
  "where": {
    "operator": "GreaterThanEqual",
    "path": [
      "inCity",
      "city",
      "name"
    ],
    "valueInt": 2000,
    "valueNumber": 3.14,
    "valueString": "my search term",
    "valueText": "my search term",
    "valueDate": "TODO",
    "valueNumberArray": [
      3.14
    ],
    "valueBooleanArray": [
      true,
      false
    ],
    "valueStringArray": [
      "my search term"
    ],
    "valueTextArray": [
      "my search term"
    ]
  }
}

Response

Search performed successfully.

tookMsinteger required

Server-side processing time in milliseconds.

Changes

No recorded changes to this operation across all 1 revision of this API.