{"id":15770,"date":"2024-05-28T15:11:01","date_gmt":"2024-05-28T22:11:01","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=15770"},"modified":"2025-06-13T20:19:14","modified_gmt":"2025-06-14T03:19:14","slug":"querying-vectors-challenges","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/querying-vectors-challenges\/","title":{"rendered":"Querying Vectors And Things That Can Go Wrong With Them"},"content":{"rendered":"

Couchbase 7.6 introduces Vector Search into the Couchbase architecture<\/a>, expanding its search capabilities by leaps and bounds. This article showcases how this affects search queries, how we have to adapt in certain situations and how to efficiently use this latest feature. To make sure your vector searches are the best they can be, you need to be aware of problems like slow queries caused by inefficient indexes, inefficient queries or frequently changing data as well as other failure cases like timeouts, consistency errors, app herder, etc.<\/span><\/p>\n

Introducing Vector Queries<\/span><\/h2>\n

Search queries had to be adapted to allow the use of vectors. It is essentially a new query type that allows <\/span>similarity search<\/span><\/i> instead of exact search. The difference being that we are not looking for exact matches anymore when it comes to vectors, but the closest ones to the vector specified in the query:<\/span><\/p>\n

{\r\n\u00a0\u00a0\"query\": {\r\n\u00a0\u00a0\u00a0\u00a0\"match_none\": {}\r\n\u00a0\u00a0},\r\n\u00a0\u00a0\"knn\": [\r\n\u00a0\u00a0\u00a0\u00a0{\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"field\": \"vector\",\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"vector\": [0.04603520780801773, ...,\u00a0 -0.08424953371286392],\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"k\": 3\r\n\u00a0\u00a0\u00a0\u00a0}\r\n\u00a0\u00a0]\r\n}<\/pre>\n
This is a vector query. It differs quite a bit from a regular query. All of the vector parts of the query are under a new key called knn<\/em>, introduced for the sole purpose of vector queries. The k<\/em> value in the query determines the number of documents you want in the results. This is necessary because instead of looking for the exact match, we are concerned about finding the k<\/em> closest vectors to the query vector. This query will end up returning three vectors that search thinks is the closest to the query vector.<\/span><\/p>\n
{\r\n\u00a0\u00a0\"query\": \u201ccontent:car\u201d,\r\n\u00a0\u00a0\"knn\": [\r\n\u00a0\u00a0\u00a0\u00a0{\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"field\": \"vector\",\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"vector\": [0.04603520780801773, ...,\u00a0 -0.08424953371286392],\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"k\": 3\r\n\u00a0\u00a0\u00a0\u00a0}\r\n\u00a0\u00a0]\r\n}<\/pre>\n
You can also combine a vector query with a regular query for a <\/span>hybrid search<\/span><\/i><\/a>. In this case, search does the query in two phases. This first phase will do the vector search, merges all of the results from the different partitions, and the second phase is where the regular search happens, utilizing the results from the first phase. This approach allows for a better performance in terms of both time and amount of data passed between the nodes.<\/span><\/p>\n
Now that we know how to query vectors, let us go through the most common failure scenarios. What can go wrong during a vector query?<\/span><\/p>\n
Identifying Slow Queries<\/span><\/h2>\n
One of the most common types of query failure is a slow query. A query which is stuck processing in the system for a long time is called a slow query. Depending on the timeout set for this query, it can stay running for a long time.<\/span><\/p>\n
There are many reasons why this happens. One of the simplest reasons for a slow query is that it is too expensive to run. This can be due to it referencing too many documents, the number of documents indexed is huge or the type of query is a comparatively inefficient one.<\/span><\/p>\n
In vector terms, the most common causes of a slow query is due to a large index size with an insufficient number of partitions, a large K value in the query, or even a high data ingest rate.<\/span><\/p>\n
Now that we know what a slow query is, the next question that comes to mind is, how do you know there is a slow query still running? One of the best ways of doing this is to check the logs. A slow query will be logged every 5 seconds. This timer can be changed using the manager options and the log line will look like:<\/span><\/p>\n
\"\"<\/a><\/span><\/p>\n
Another way is to look at the stats. There is a stat available in the <\/span>\/api\/nsstats<\/span><\/i> endpoint called <\/span>total_queries_slow<\/span><\/i> which will log the number of times a slow query has been detected:<\/span><\/p>\n
\"\"<\/a><\/p>\n
There are also a few more stats that you can observe in the same endpoint that might give us some clue as to what is happening to the query internally and where the trouble might be:<\/span><\/p>\n