Apply Metadata Filters to Vector Search Results - DashVector

Vector similarity search alone rarely meets real-world requirements. Applications typically need to narrow results by metadata -- for example, returning only products within a price range or documents from a specific category. DashVector conditional filtering lets you attach metadata fields to vectors and pass a filter expression at query time, so only vectors matching your conditions are included in similarity results.

Quick start

This example queries a collection for males older than 18 who weigh more than 65 kg:

docs = collection.query(
    [0.1, 0.1, 0.1, 0.1],
    topk=10,
    filter='age > 18 and weight > 65.0 and male = true'
)

The filter parameter accepts a boolean expression built from comparison, string, and logical operators. For the full syntax, see Filter expression syntax.

Prerequisites

Before you begin, make sure that you have:

A DashVector API key and cluster endpoint
A collection named quickstart. For setup instructions, see the "Example" section in Create a collection

Insert documents with metadata fields

Insert documents into the quickstart collection. Each document includes an ID, a 4-dimensional vector, and a set of metadata fields:

import dashvector
import numpy as np

client = dashvector.Client(
    api_key='<your-api-key>',
    endpoint='<your-cluster-endpoint>'
)
collection = client.get(name='quickstart')

ret = collection.insert([
    ('1', np.random.rand(4), {'name': 'alice', 'age': 10, 'male': True, 'weight': 35.0}),
    ('2', np.random.rand(4), {'name': 'bob', 'age': 20, 'male': False, 'weight': 45.0}),
    ('3', np.random.rand(4), {'name': 'carol', 'age': 30, 'male': True, 'weight': 75.0}),
    ('4', np.random.rand(4), {'name': 'dave', 'age': 5, 'male': False, 'weight': 18.0}),
    ('5', np.random.rand(4), {'name': 'eve', 'age': 40, 'male': True, 'weight': 70.0})
])
assert ret

Replace the following placeholders with your actual values:

Placeholder	Description
`<your-api-key>`	Your DashVector API key
`<your-cluster-endpoint>`	Your cluster endpoint URL

Note

The quickstart collection is created with three predefined fields: name (str), weight (float), and age (int). Because DashVector is schema-free, you can add fields not defined at collection creation time -- such as the male field above -- when inserting documents.

Query with a filter expression

Pass a filter string to collection.query() to restrict results. This example searches for males older than 18 who weigh more than 65 kg:

import dashvector

client = dashvector.Client(
    api_key='<your-api-key>',
    endpoint='<your-cluster-endpoint>'
)
collection = client.get(name='quickstart')

# Filter: males over 18 weighing more than 65 kg
docs = collection.query(
    [0.1, 0.1, 0.1, 0.1],
    topk=10,
    filter='age > 18 and weight > 65.0 and male = true'
)
print(docs)

Filter expression syntax

A filter expression consists of one or more conditions joined by logical operators. Each condition follows the pattern:

<field> <operator> <value>

Comparison operators

Operator	Description	Supported types	Example	Matches when
`<`	Less than	`int`, `float`	`age < 10`	`age` is less than 10
`<=`	Less than or equal to	`int`, `float`	`weight <= 60.0`	`weight` is at most 60.0
`=`	Equal to	`int`, `float`, `bool`, `str`	`name = 'alice'`	`name` equals `alice`
`!=`	Not equal to	`int`, `float`, `bool`, `str`	`male != true`	`male` is not true
`>=`	Greater than or equal to	`int`, `float`	`age >= 10`	`age` is at least 10
`>`	Greater than	`int`, `float`	`weight > 60.0`	`weight` exceeds 60.0

String operator

Use the like operator for prefix matching on str fields.

Operator	Description	Example	Matches when
`like`	Prefix match	`name like 'al%'`	`name` starts with `al`

Logical operators

Combine multiple conditions with and or or.

Operator	Description	Example	Matches when
`and`	Both conditions must be true	`age > 18 and male = true`	`age` exceeds 18 and `male` is true
`or`	At least one condition must be true	`age < 10 or age > 60`	`age` is under 10 or over 60

Use parentheses () to control evaluation order. For example:

age > 18 and (weight > 65.0 or male = true)

This expression first evaluates (weight > 65.0 or male = true), then combines the result with age > 18.

Supported field types

DashVector fields support the following Python data types:

Type	Description	Range
`str`	String	--
`int`	Integer	32-bit signed: -2,147,483,648 to 2,147,483,647
`float`	Floating-point number	--
`bool`	Boolean	`True` or `False`

Important

Python integers have unlimited size, but DashVector only supports 32-bit signed integers. Make sure integer values stay within the range of -2,147,483,648 to 2,147,483,647 to avoid overflow.