Note
This feature is an experimental feature in the current version.
This topic describes vector search, hybrid search, exact query, filter conditions, and QueryHint.
Create sample data
Assume that the pyseekdb connection has been established (the client variable is available). If an object with the same name already exists, you can delete it and create a new one, or use get_or_create_.
from pyseekdb import Schema, VectorIndexConfig, IVFConfiguration, FulltextIndexConfig
from pyseekdb.utils.embedding_functions import DefaultEmbeddingFunction
collection = client.create_collection(
name="tech_docs1",
schema=Schema(
vector_index=VectorIndexConfig(
ivf=IVFConfiguration(dimension=384, distance="cosine"),
embedding_function=DefaultEmbeddingFunction(),
),
fulltext_index=FulltextIndexConfig(analyzer="ik"),
),
use_namespace=True,
)
ns = collection.create_namespace("my_knowledge1")
Write six sample documents containing similar text but different category values to observe the recall changes after filtering:
ns.add(
ids=["doc1", "doc2", "doc3", "doc4", "doc5", "doc6"],
documents=[
"OceanBase AI Database is a distributed database independently developed by Ant Group, supporting HTAP mixed workloads.",
"Agent Hybrid Search Scenario is a multi-tenant vector search solution for AI Agents in OceanBase AI Database.",
"pyseekdb is the Python SDK for OceanBase AI Database, providing vector storage and hybrid search capabilities.",
"OceanBase AI Database delivers high availability in distributed databases through multi-replica deployment and log replication.",
"Agent Memory uses vector search to preserve session context and long-term memory.",
"Using pyseekdb, you can perform hybrid vector and full-text search within the same Namespace.",
],
metadatas=[
{"category": "database", "version": "4.0"},
{"category": "ai", "version": "4.6"},
{"category": "sdk", "version": "1.2"},
{"category": "database", "version": "4.2"},
{"category": "ai", "version": "4.7"},
{"category": "sdk", "version": "1.3"},
],
)
Vector search (query)
Notice
You must specify at least one of query_embeddings and query_texts. If neither is provided, an error will be returned.
Query by text (recommended)
The following example uses where={"category": "database"} as the filter. Among the six samples, only doc1 and doc4 match this category, making it easier to observe the filtering effect. query_texts supports searching for multiple query texts simultaneously:
results = ns.query(
query_texts=["Distributed Database"],
n_results=5,
where={"category": "database"},
include=["documents", "metadatas", "distances"],
)
A sample result is shown below (indicating distance and sorting; actual values may vary slightly with the model and data):
#1: doc1 (distance=0.2310)
OceanBase AI Database is a distributed database independently developed by Ant Group, supporting HTAP mixed workload.
{'category': 'database', 'version': '4.0'}
#2: doc4 (distance=0.2780)
OceanBase AI Database provides high availability for distributed databases through multi-replica deployment and log replication.
{'category': 'database', 'version': '4.2'}
query returns a two-dimensional result. The outer layer corresponds to each query vector/text, and the inner layer corresponds to the result list.
Query by vector
results = ns.query(
query_embeddings=[[0.12, 0.34, ...]],
n_results=10,
)
Hybrid search (hybrid_search)
Simultaneously performs full-text search and vector search, then returns the merged sorted results:
# Full-text query: search for documents containing the word "database" and filter by category=database.
# Vector-based routing (KNN): uses "distributed database high availability" for nearest neighbor search
# The two streams of results are fused using RRF, and the top 3 are selected.
results = ns.hybrid_search(
query={
"where_document": {"$contains": "database"},
"where": {"category": {"$eq": "database"}},
"n_results": 6,
},
knn={
"query_texts": ["High availability of distributed databases"],
"n_results": 6,
},
rank={"rrf": {"rank_window_size": 60, "rank_constant": 60}},
n_results=3,
include=["documents", "metadatas", "distances"],
)
for i, id_ in enumerate(results["ids"][0]):
print(f"#{i+1}: {id_} (distance={results['distances'][0][i]:.4f})")
For parameter descriptions, see hybrid_search.
Exact search (get)
# Query by ID
result = ns.get(ids=["doc1", "doc2"])
# Conditional query + pagination
result = ns.get(
where={"category": "database"},
limit=2,
offset=0,
include=["documents", "metadatas"],
)
General parameters and return values
Parameter |
Applicable methods |
Note |
|---|---|---|
| n_results | query / hybrid_search | Number of records returned. Default: 10. |
| include | query / hybrid_search / get | Response parameters: "documents" / "metadatas" / "embeddings". distances is always returned in query/hybrid_search. |
| where | All | Metadata filtering. For more information, see the following sections. |
| where_document | All | Filter by document. For more information, see the following sections. |
Return value structure:
query/hybrid_search: Two-dimensional. The outer layer corresponds to each query text/vector, and the inner layer is the result list. For example,{"ids": [["doc1", "doc4"]], "distances": [[0.12, 0.18]], ...}.get: One-dimensional. For example,{"ids": ["doc1", "doc4"], "documents": [...], "metadatas": [...]}.
The distances returned by hybrid_search are typically fused relevance scores and may not equal vector distances. In namespace mode, you can directly use query() for vector search, which yields the same results as using only the hybrid_search knn path.
Filter conditions
Filter conditions apply to the query, hybrid_search, get, and delete methods.
Metadata filtering (where)
Comparison operators (the following table shows syntax examples; in this scenario, the data fields are category or version):
Operators |
Meaning |
Example |
|---|---|---|
| $eq | equal to | {"category": {"$eq": "database"}} |
| $ne | Not equal to | {"category": {"$ne": "sdk"}} |
| $lt / $lte | Less Than / Less Than or Equal To | {"version": {"$lt": "4.6"}} |
| $gt / $gte | Greater Than / Greater Than or Equal To | {"version": {"$gte": "4.0"}} |
| $in | In the list | {"category": {"$in": ["database", "ai"]}} |
| $nin | Not in list | {"category": {"$nin": ["sdk"]}} |
Logical combinations:
# AND + NOT
{"$and": [{"category": {"$eq": "database"}}, {"$not": {"version": {"$eq": "1.2"}}}]}
Document filtering (where_document)
# Full-text search
{"$contains": "distributed database"}
# Regular Expression Match
{"$regex": "^OceanBase.*"}
# does not contain
{"$not_contains": "Obsolete content"}
# Logical combination
{"$or": [{"$contains": "OceanBase"}, {"$contains": "database"}]}
$not_contains and $regex cannot be pushed down to vector filtering in some hybrid/knn scenarios and will be filtered post-processing by the SDK.
Combined usage
results = ns.query(
query_texts=["Distributed Technology"],
n_results=10,
# Multiple conditions in parallel
where={
"$and": [
{"category": {"$in": ["database", "ai"]}},
{"version": {"$in": ["4.0", "4.2", "4.6", "4.7"]}},
]
},
# Full-text search
where_document={"$contains": "OceanBase"},
)
QueryHint query optimization
QueryHint is used to control query parallelism and timeout. In this scenario, query_hint applies to hybrid search:
from pyseekdb import QueryHint
results = ns.hybrid_search(
query={"where_document": {"$contains": "database"}, "n_results": 10},
knn={"query_texts": ["Distributed Technology"], "n_results": 10},
n_results=5,
query_hint=QueryHint(
parallel=8, # Query parallelism, must be > 0
query_timeout=10.0, # Timeout duration (seconds), must be > 0
vector_index=True, # Whether to use the vector index hint
),
)
Parameters |
Type |
Note |
|---|---|---|
| parallel | int | Query parallelism, which must be greater than 0. |
| query_timeout | float | Query timeout in seconds. The value must be greater than 0. |
| vector_index | bool | Whether to add a vector index hint |
Limitations:
query_hintonly takes effect forhybrid_search. It is not supported forns.query()orns.get()at present.