> ## Documentation Index > Fetch the complete documentation index at: https://opendata.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search for nearest neighbors > Return the top `k` records for a query. Provide exactly one of `vector` (approximate nearest neighbor search) or `bm25` (full-text BM25 search over a text field); the two are mutually exclusive. Optionally filter results by metadata attributes using a filter expression. The `nprobe` parameter controls how many posting lists are searched for ANN queries. Higher values improve recall at the cost of latency. The `includeFields` parameter controls which attributes are returned for each result. When omitted, all attributes are returned. Supports both binary protobuf (`application/protobuf`) and ProtoJSON (`application/protobuf+json`) request bodies. ## OpenAPI ````yaml /openapi/vector.yaml post /api/v1/vector/search openapi: 3.1.0 info: title: OpenData Vector API version: 1.0.0 description: >- HTTP API for the OpenData Vector service — a semantic search database on object storage. servers: - url: http://localhost:8080 description: Local development server security: [] paths: /api/v1/vector/search: post: summary: Search for nearest neighbors description: | Return the top `k` records for a query. Provide exactly one of `vector` (approximate nearest neighbor search) or `bm25` (full-text BM25 search over a text field); the two are mutually exclusive. Optionally filter results by metadata attributes using a filter expression. The `nprobe` parameter controls how many posting lists are searched for ANN queries. Higher values improve recall at the cost of latency. The `includeFields` parameter controls which attributes are returned for each result. When omitted, all attributes are returned. Supports both binary protobuf (`application/protobuf`) and ProtoJSON (`application/protobuf+json`) request bodies. operationId: search requestBody: required: true content: application/protobuf+json: schema: $ref: '#/components/schemas/SearchRequest' examples: ann: summary: Vector (ANN) search value: vector: - 1 - 2 - 3 k: 10 nprobe: 20 filter: eq: field: category value: electronics fullText: summary: Full-text (BM25) search value: bm25: field: description query: wireless noise cancelling headphones k: 10 filter: eq: field: category value: electronics application/protobuf: schema: type: string format: binary responses: '200': description: Search results ranked by similarity. content: application/protobuf+json: schema: $ref: '#/components/schemas/SearchResponse' example: status: success results: - score: 0.05 vector: id: doc-1 attributes: vector: - 1 - 2 - 3 category: electronics '400': description: Invalid input (empty vector, k is 0, malformed filter). content: application/protobuf+json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/protobuf+json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: bash label: Full-text (BM25) search source: | curl -X POST http://localhost:8080/api/v1/vector/search \ -H 'Content-Type: application/json' \ -d '{ "bm25": { "field": "description", "query": "wireless noise cancelling headphones" }, "k": 10, "filter": { "eq": { "field": "category", "value": "electronics" } } }' - lang: bash label: Vector (ANN) search source: | curl -X POST http://localhost:8080/api/v1/vector/search \ -H 'Content-Type: application/json' \ -d '{ "vector": [1.0, 2.0, 3.0], "k": 10, "nprobe": 20, "filter": { "eq": { "field": "category", "value": "electronics" } } }' components: schemas: SearchRequest: type: object description: | Request body for searching a collection. Provide exactly one of `vector` (approximate nearest neighbor search) or `bm25` (full-text BM25 search); they are mutually exclusive. properties: vector: type: array items: type: number format: float description: >- Query vector for ANN search. Must have the same number of dimensions as the collection. Provide either this or `bm25`. bm25: type: object description: >- Full-text BM25 query over a text field. Provide either this or `vector`. properties: field: type: string description: Name of the Text attribute to search. query: type: string description: Query string, tokenized and scored with BM25 against the field. required: - field - query k: type: integer format: uint32 minimum: 1 description: Number of results to return. nprobe: type: integer format: uint32 description: >- Number of posting lists to search for ANN queries. Higher values improve recall at the cost of latency. Optional. filter: $ref: '#/components/schemas/Filter' includeFields: type: array items: type: string description: >- List of attribute field names to include in results. When omitted, all attributes are returned. required: - k SearchResponse: type: object description: Response containing search results ranked by similarity. properties: status: type: string example: success results: type: array items: $ref: '#/components/schemas/SearchResult' required: - status - results ErrorResponse: type: object description: Error response returned for all error cases. properties: status: type: string example: error message: type: string description: Human-readable error message. required: - status - message Filter: type: object description: | A filter expression. Each filter object must contain exactly one operator key. Filters can be nested using `and` and `or`. properties: eq: $ref: '#/components/schemas/ComparisonFilter' neq: $ref: '#/components/schemas/ComparisonFilter' in: $ref: '#/components/schemas/InFilter' and: type: array items: $ref: '#/components/schemas/Filter' description: Logical AND — all sub-filters must match. or: type: array items: $ref: '#/components/schemas/Filter' description: Logical OR — at least one sub-filter must match. SearchResult: type: object description: A single search result with a similarity score and the matched vector. properties: score: type: number format: float description: | Similarity score. For L2 distance, lower scores mean higher similarity. For dot product, higher scores mean higher similarity. vector: $ref: '#/components/schemas/Vector' required: - score - vector ComparisonFilter: type: object description: Filter that compares a field to a scalar value. properties: field: type: string description: The attribute field name to compare. value: $ref: '#/components/schemas/AttributeValue' required: - field - value InFilter: type: object description: Filter that checks if a field value is in a set of values. properties: field: type: string description: The attribute field name to check. values: type: array items: $ref: '#/components/schemas/AttributeValue' description: Set of values to match against. required: - field - values Vector: type: object description: A record with an ID and attributes, including the embedding vector. properties: id: type: string maxLength: 64 description: User-provided unique identifier (up to 64 bytes). attributes: $ref: '#/components/schemas/Attributes' required: - id - attributes AttributeValue: description: | A metadata attribute value. In JSON, values are represented as plain scalars or arrays — strings, integers, floats, booleans, or arrays of floats (for the vector field). oneOf: - type: string description: String attribute value. - type: integer format: int64 description: 64-bit signed integer attribute value. - type: number format: double description: 64-bit floating point attribute value. - type: boolean description: Boolean attribute value. - type: array items: type: number format: float description: >- Vector attribute (array of f32 values). Used for the reserved `vector` field. Attributes: type: object description: | A flat map of attribute names to values. Must include a `vector` key with an array of floats matching the collection's configured dimensions. Other keys are metadata attributes whose types must match the collection schema (if defined). additionalProperties: $ref: '#/components/schemas/AttributeValue' required: - vector ````