@mastra/qdrant 0.10.3 → 0.11.0-alpha.1

package/src/vector/filter.ts

@@ -1,5 +1,103 @@
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
-import type { FieldCondition, VectorFilter, LogicalOperator, OperatorSupport } from '@mastra/core/vector/filter';
+import type {
+  VectorFilter,
+  LogicalOperator,
+  OperatorSupport,
+  OperatorValueMap,
+  LogicalOperatorValueMap,
+  BlacklistedRootOperators,
+} from '@mastra/core/vector/filter';
+
+type QdrantOperatorValueMap = Omit<OperatorValueMap, '$options' | '$elemMatch' | '$all'> & {
+  /**
+   * $count: Filter by array length or value count.
+   * Example: { tags: { $count: { gt: 2 } } }
+   */
+  $count: {
+    $gt?: number;
+    $gte?: number;
+    $lt?: number;
+    $lte?: number;
+    $eq?: number;
+  };
+
+  /**
+   * $geo: Geospatial filter.
+   * Example: { location: { $geo: { type: 'geo_radius', center: [lon, lat], radius: 1000 } } }
+   */
+  $geo: {
+    type: string;
+    [key: string]: any;
+  };
+
+  /**
+   * $hasId: Filter by point IDs.
+   * Allowed at root level.
+   * Example: { $hasId: '123' } or { $hasId: ['123', '456'] }
+   */
+  $hasId: string | string[];
+
+  /**
+   * $nested: Nested object filter.
+   * Example: { metadata: { $nested: { key: 'foo', filter: { $eq: 'bar' } } } }
+   */
+  $nested: {
+    // Additional properties depend on the nested object structure
+    [key: string]: any;
+  };
+
+  /**
+   * $hasVector: Filter by vector existence or field.
+   * Allowed at root level.
+   * Example: { $hasVector: true } or { $hasVector: 'vector_field' }
+   */
+  $hasVector: boolean | string;
+
+  /**
+   * $datetime: RFC 3339 datetime range.
+   * Example: { createdAt: { $datetime: { gte: '2024-01-01T00:00:00Z' } } }
+   */
+  $datetime: {
+    key?: string;
+    range?: {
+      gt?: Date | string;
+      gte?: Date | string;
+      lt?: Date | string;
+      lte?: Date | string;
+      eq?: Date | string;
+    };
+  };
+
+  /**
+   * $null: Check if a field is null.
+   * Example: { metadata: { $null: true } }
+   */
+  $null: boolean;
+
+  /**
+   * $empty: Check if an array or object field is empty.
+   * Example: { tags: { $empty: true } }
+   */
+  $empty: boolean;
+};
+
+type QdrantLogicalOperatorValueMap = Omit<LogicalOperatorValueMap, '$nor'>;
+
+type QdrantBlacklistedRootOperators =
+  | BlacklistedRootOperators
+  | '$count'
+  | '$geo'
+  | '$nested'
+  | '$datetime'
+  | '$null'
+  | '$empty';
+
+export type QdrantVectorFilter = VectorFilter<
+  keyof QdrantOperatorValueMap,
+  QdrantOperatorValueMap,
+  QdrantLogicalOperatorValueMap,
+  QdrantBlacklistedRootOperators
+>;
 
 /**
  * Translates MongoDB-style filters to Qdrant compatible filters.
@@ -20,7 +118,7 @@ import type { FieldCondition, VectorFilter, LogicalOperator, OperatorSupport } f
  * - $null -> is_null check
  * - $empty -> is_empty check
  */
-export class QdrantFilterTranslator extends BaseFilterTranslator {
+export class QdrantFilterTranslator extends BaseFilterTranslator<QdrantVectorFilter> {
   protected override isLogicalOperator(key: string): key is LogicalOperator {
     return super.isLogicalOperator(key) || key === '$hasId' || key === '$hasVector';
   }
@@ -35,7 +133,7 @@ export class QdrantFilterTranslator extends BaseFilterTranslator {
     };
   }
 
-  translate(filter?: VectorFilter): VectorFilter {
+  translate(filter?: QdrantVectorFilter): QdrantVectorFilter {
     if (this.isEmpty(filter)) return filter;
     this.validateFilter(filter);
     return this.translateNode(filter);
@@ -46,8 +144,8 @@ export class QdrantFilterTranslator extends BaseFilterTranslator {
     return fieldKey ? { key: fieldKey, ...condition } : condition;
   }
 
-  private translateNode(node: VectorFilter | FieldCondition, isNested: boolean = false, fieldKey?: string): any {
-    if (!this.isEmpty(node) && typeof node === 'object' && 'must' in node) {
+  private translateNode(node: QdrantVectorFilter, isNested: boolean = false, fieldKey?: string): any {
+    if (!this.isEmpty(node) && !!node && typeof node === 'object' && 'must' in node) {
       return node;
     }
 

package/src/vector/index.test.ts

@@ -3,6 +3,7 @@
 import type { QueryResult } from '@mastra/core';
 import { describe, it, expect, beforeAll, afterAll, afterEach, vi, beforeEach } from 'vitest';
 
+import type { QdrantVectorFilter } from './filter';
 import { QdrantVector } from './index';
 
 const dimension = 3;
@@ -77,7 +78,7 @@ describe('QdrantVector', () => {
 
     it('should query vectors with metadata filter', async () => {
       const queryVector = [0.0, 1.0, 0.0];
-      const filter = {
+      const filter: QdrantVectorFilter = {
         label: 'y-axis',
       };
 
@@ -350,21 +351,21 @@ describe('QdrantVector', () => {
 
     describe('Basic Operators', () => {
       it('should filter by exact value match', async () => {
-        const filter = { name: 'item1' };
+        const filter: QdrantVectorFilter = { name: 'item1' };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
         expect(results).toHaveLength(1);
         expect(results[0]?.metadata?.name).toBe('item1');
       });
 
       it('should filter using comparison operators', async () => {
-        const filter = { price: { $gt: 100, $lt: 600 } };
+        const filter: QdrantVectorFilter = { price: { $gt: 100, $lt: 600 } };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
         expect(results).toHaveLength(1);
         expect(results[0]?.metadata?.price).toBe(500);
       });
 
       it('should filter using array operators', async () => {
-        const filter = { tags: { $in: ['premium', 'bestseller'] } };
+        const filter: QdrantVectorFilter = { tags: { $in: ['premium', 'bestseller'] } };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
         expect(results).toHaveLength(2);
         const tags = results.flatMap(r => r.metadata?.tags || []);
@@ -373,14 +374,14 @@ describe('QdrantVector', () => {
       });
 
       it('should handle null values', async () => {
-        const filter = { price: null };
+        const filter: QdrantVectorFilter = { price: null };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
         expect(results).toHaveLength(1);
         expect(results[0]?.metadata?.price).toBeNull();
       });
 
       it('should handle empty arrays', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           tags: [],
         };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
@@ -392,7 +393,7 @@ describe('QdrantVector', () => {
 
     describe('Logical Operators', () => {
       it('should combine conditions with $and', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $and: [{ tags: { $in: ['electronics'] } }, { price: { $gt: 700 } }],
         };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
@@ -402,7 +403,7 @@ describe('QdrantVector', () => {
       });
 
       it('should combine conditions with $or', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $or: [{ price: { $gt: 900 } }, { tags: { $in: ['bestseller'] } }],
         };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
@@ -413,7 +414,7 @@ describe('QdrantVector', () => {
       });
 
       it('should handle $not operator', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $not: { tags: { $in: ['electronics'] } },
         };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
@@ -425,7 +426,7 @@ describe('QdrantVector', () => {
       });
 
       it('should handle nested logical operators', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $and: [
             { 'details.weight': { $lt: 2.0 } },
             {
@@ -442,7 +443,7 @@ describe('QdrantVector', () => {
       });
 
       it('should handle empty logical operators', async () => {
-        const filter = { $and: [] };
+        const filter: QdrantVectorFilter = { $and: [] };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
         expect(results.length).toBeGreaterThan(0);
       });
@@ -450,7 +451,7 @@ describe('QdrantVector', () => {
 
     describe('Custom Operators', () => {
       it('should filter using $count operator', async () => {
-        const filter = { 'stock.locations': { $count: { $gt: 1 } } };
+        const filter: QdrantVectorFilter = { 'stock.locations': { $count: { $gt: 1 } } };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
         expect(results).toHaveLength(2);
         results.forEach(result => {
@@ -459,7 +460,7 @@ describe('QdrantVector', () => {
       });
 
       it('should filter using $geo radius operator', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           location: {
             $geo: {
               type: 'radius',
@@ -475,7 +476,7 @@ describe('QdrantVector', () => {
       });
 
       it('should filter using $geo box operator', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           location: {
             $geo: {
               type: 'box',
@@ -491,7 +492,7 @@ describe('QdrantVector', () => {
       });
 
       it('should filter using $geo polygon operator', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           location: {
             $geo: {
               type: 'polygon',
@@ -518,7 +519,7 @@ describe('QdrantVector', () => {
         const allResults = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], topK: 2 });
         const targetIds = allResults.map(r => r.id);
 
-        const filter = { $hasId: targetIds };
+        const filter: QdrantVectorFilter = { $hasId: targetIds };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
         expect(results).toHaveLength(2);
         results.forEach(result => {
@@ -527,7 +528,7 @@ describe('QdrantVector', () => {
       });
 
       it('should filter using $hasVector operator', async () => {
-        const filter = { $hasVector: '' };
+        const filter: QdrantVectorFilter = { $hasVector: '' };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
         expect(results.length).toBeGreaterThan(0);
       });
@@ -543,7 +544,7 @@ describe('QdrantVector', () => {
         };
         await qdrant.upsert({ indexName: testCollectionName, vectors: [vector], metadata: [metadata] });
 
-        const filter = {
+        const filter: QdrantVectorFilter = {
           created_at: {
             $datetime: {
               range: {
@@ -603,7 +604,7 @@ describe('QdrantVector', () => {
         expect(results.length).toBe(2);
       });
       it('should handle nested paths', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           'details.color': 'red',
           'stock.quantity': { $gt: 0 },
         };
@@ -614,7 +615,7 @@ describe('QdrantVector', () => {
       });
 
       it('should handle multiple conditions on same field', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           price: { $gt: 20, $lt: 30 },
         };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
@@ -623,7 +624,7 @@ describe('QdrantVector', () => {
       });
 
       it('should handle complex combinations', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $and: [
             { 'details.weight': { $lt: 3.0 } },
             {
@@ -642,7 +643,7 @@ describe('QdrantVector', () => {
       });
 
       it('should handle array paths with nested objects', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           'stock.locations[].warehouse': { $in: ['A'] },
         };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
@@ -653,7 +654,7 @@ describe('QdrantVector', () => {
       });
 
       it('should handle multiple nested paths with array notation', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $and: [{ 'stock.locations[].warehouse': { $in: ['A'] } }, { 'stock.locations[].count': { $gt: 20 } }],
         };
         const results = await qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter });
@@ -677,7 +678,7 @@ describe('QdrantVector', () => {
         };
         await qdrant.upsert({ indexName: testCollectionName, vectors: [vector], metadata: [metadata] });
 
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $and: [
             {
               'timestamps.created': {
@@ -696,7 +697,7 @@ describe('QdrantVector', () => {
       });
 
       it('should handle complex combinations with custom operators', async () => {
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $and: [
             { 'stock.locations': { $count: { $gt: 0 } } },
             {
@@ -731,7 +732,7 @@ describe('QdrantVector', () => {
     describe('Performance Cases', () => {
       it('should handle deep nesting efficiently', async () => {
         const start = Date.now();
-        const filter = {
+        const filter: QdrantVectorFilter = {
           $and: Array(5)
             .fill(null)
             .map(() => ({
@@ -745,7 +746,11 @@ describe('QdrantVector', () => {
       });
 
       it('should handle multiple concurrent filtered queries', async () => {
-        const filters = [{ price: { $gt: 500 } }, { tags: { $in: ['electronics'] } }, { 'stock.quantity': { $gt: 0 } }];
+        const filters: QdrantVectorFilter[] = [
+          { price: { $gt: 500 } },
+          { tags: { $in: ['electronics'] } },
+          { 'stock.quantity': { $gt: 0 } },
+        ];
         const start = Date.now();
         const results = await Promise.all(
           filters.map(filter => qdrant.query({ indexName: testCollectionName, queryVector: [1, 0, 0], filter })),