search

Search a collection with near-object

Performs a similarity search over the objects of a collection, anchored at an existing object: the stored vector of the source object (referenced by id) is searched against the vector index and the closest objects are returned — the source object itself included — 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.

post/search/{collection}/near-object

Request

  • Base URL: https://localhost:8080/v1
  • URL: https://localhost:8080/v1/search/{collection}/near-object
  • 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).

idstring uuid required

The UUID of the source object whose stored vector anchors the search. A structurally invalid UUID is rejected at request validation; a well-formed UUID that matches no object in the collection is rejected with 400.

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 source object's vector for this name anchors the search). 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.