Skip to main content
Preview
Preview Feature — This feature is currently in preview and under active development. APIs and functionality may change. We recommend testing thoroughly before using in production.

Querying Vectors

Learn how to search and retrieve vectors from your vector database using similarity search.

Basic Query​

Find vectors similar to a query vector:

const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,  // Array of numbers
  topK: 10,             // Number of results to return
});

console.log('Matches:', results.matches);

Query Options​

OptionTypeDefaultDescription
vectornumber[]RequiredQuery vector
topKnumber10Maximum results to return
filterobject-Metadata filter
includeMetadatabooleanfalseInclude metadata in results
includeValuesbooleanfalseInclude vector values in results
namespacestring'default'Namespace to search in
minScorenumber-Minimum similarity score threshold

Including Metadata​

Retrieve metadata with results:

const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 5,
  includeMetadata: true,
});

results.matches.forEach((match) => {
  console.log(`ID: ${match.id}`);
  console.log(`Score: ${match.score}`);
  console.log(`Title: ${match.metadata?.title}`);
  console.log(`Category: ${match.metadata?.category}`);
});

Filtering Results​

Exact Match​

const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  filter: {
    category: 'electronics',
  },
  includeMetadata: true,
});

Multiple Conditions (AND)​

const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  filter: {
    category: 'electronics',
    in_stock: true,
  },
});

Comparison Operators​

// Price less than 100
const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  filter: {
    price: { $lt: 100 },
  },
});

// Rating greater than or equal to 4
const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  filter: {
    rating: { $gte: 4 },
  },
});

Available Operators​

OperatorDescriptionExample
$eqEqual to{ status: { $eq: 'active' } }
$neNot equal to{ status: { $ne: 'deleted' } }
$gtGreater than{ price: { $gt: 50 } }
$gteGreater than or equal{ rating: { $gte: 4 } }
$ltLess than{ price: { $lt: 100 } }
$lteLess than or equal{ quantity: { $lte: 10 } }
$inIn array{ category: { $in: ['books', 'media'] } }
$ninNot in array{ status: { $nin: ['deleted', 'archived'] } }

Complex Filters​

const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  filter: {
    $and: [
      { category: 'electronics' },
      { price: { $lt: 500 } },
      { rating: { $gte: 4 } },
    ],
  },
});

const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  filter: {
    $or: [
      { category: 'electronics' },
      { category: 'computers' },
    ],
  },
});

Minimum Score Threshold​

Only return results above a similarity threshold:

const results = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  minScore: 0.7,  // Only results with 70%+ similarity
  includeMetadata: true,
});

Namespaces​

Query within a specific namespace:

// Query in 'products' namespace
const productResults = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  namespace: 'products',
});

// Query in 'articles' namespace
const articleResults = await ductape.vector.query({
  tag: 'my-vectors',
  vector: queryVector,
  topK: 10,
  namespace: 'articles',
});

Understanding Similarity Scores​

Scores depend on your distance metric:

Cosine Similarity​

  • Range: 0 to 1 (higher is more similar)
  • 1.0 = identical direction
  • 0.0 = orthogonal (unrelated)

Euclidean Distance​

  • Range: 0 to infinity (lower is more similar)
  • 0.0 = identical
  • Results often converted to similarity score

Dot Product​

  • Range: varies (higher is more similar)
  • Best with normalized vectors

Query Patterns​

async function semanticSearch(query: string, limit: number = 10) {
  const queryVector = await getEmbedding(query);

  const results = await ductape.vector.query({
    tag: 'my-vectors',
    vector: queryVector,
    topK: limit,
    includeMetadata: true,
  });

  return results.matches.map((match) => ({
    id: match.id,
    score: match.score,
    content: match.metadata?.content,
  }));
}

const articles = await semanticSearch('machine learning tutorials');

Find Similar Items​

async function findSimilar(itemId: string, limit: number = 5) {
  // Fetch the item's vector
  const item = await ductape.vector.fetchVectors({
    tag: 'my-vectors',
    ids: [itemId],
  });
  const vector = item.vectors[itemId].values;

  // Query for similar items, excluding the original
  const results = await ductape.vector.query({
    tag: 'my-vectors',
    vector,
    topK: limit + 1,  // +1 to account for the item itself
    includeMetadata: true,
  });

  // Filter out the original item
  return results.matches
    .filter((match) => match.id !== itemId)
    .slice(0, limit);
}

const similarProducts = await findSimilar('prod-123');

Combine vector similarity with metadata filters:

async function hybridSearch(
  query: string,
  category: string,
  priceRange: { min: number; max: number }
) {
  const queryVector = await getEmbedding(query);

  const results = await ductape.vector.query({
    tag: 'my-vectors',
    vector: queryVector,
    topK: 20,
    filter: {
      category,
      price: {
        $gte: priceRange.min,
        $lte: priceRange.max,
      },
    },
    includeMetadata: true,
  });

  return results.matches;
}

const products = await hybridSearch(
  'wireless headphones',
  'electronics',
  { min: 50, max: 200 }
);

Next Steps​