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.

Getting Started with Vector Databases

This guide walks you through setting up your first vector database in Ductape.

Prerequisites

Before you begin, make sure you have:

1. A Ductape account and workspace
2. A product created in your workspace
3. Access to a vector database provider (Pinecone, Qdrant, Weaviate, or ChromaDB)
4. The Ductape SDK installed in your project

Step 1: Install the SDK

TypeScript

npm install @ductape/sdk@latest

NestJS

npm install @ductape/nestjs@latest @ductape/sdk@latest

Step 2: Initialize the SDK

TypeScript

import Ductape from '@ductape/sdk';

const ductape = new Ductape({
  accessKey: 'your-access-key',
});

Set product and env on the constructor only — see SDK runtime defaults.

Step 3: Create a Vector Database Configuration

Register your vector database with environment-specific settings:

TypeScript

import { VectorDBType, DistanceMetric } from '@ductape/sdk';

await ductape.vector.create({
  name: 'Product Embeddings',
  tag: 'product-vectors',
  type: VectorDBType.PINECONE,
  dimensions: 1536,  // Must match your embedding model
  metric: DistanceMetric.COSINE,
  envs: [
    {
      slug: 'dev',
      endpoint: 'https://dev-xxx.svc.pinecone.io',
      apiKey: process.env.PINECONE_DEV_KEY,
      index: 'products-dev',
      namespace: 'default',
    },
    {
      slug: 'prd',
      endpoint: 'https://prod-xxx.svc.pinecone.io',
      apiKey: process.env.PINECONE_PROD_KEY,
      index: 'products-prod',
      namespace: 'default',
    },
  ],
});

Cloud-linked vectors — provision or import from AWS OpenSearch, GCP Vertex AI Vector Search, or Azure AI Search.

Check available tiers for OpenSearch before provisioning:

TypeScript

const tiers = await ductape.cloud.tiers.list({ provider: 'aws', resource_type: 'vector' });

TypeScript

// AWS OpenSearch
await ductape.vector.create({
  name: 'Product Embeddings',
  tag: 'product-vectors',
  type: 'opensearch',
  dimensions: 1536,
  envs: [{
    slug: 'prd',
    cloud: 'prod_aws',
    instance: 'my-opensearch-domain',
    tier: 't3.small.search',   // from cloud.tiers.list()
    region: 'us-east-1',
  }],
});

// GCP Vertex AI Vector Search
await ductape.vector.create({
  name: 'Product Embeddings',
  tag: 'product-vectors',
  type: 'vertex-vector-search',
  dimensions: 1536,
  envs: [{
    slug: 'prd',
    cloud: 'gcp_prod',
    instance: 'my-vector-endpoint',
    region: 'us-central1',
  }],
});

// Azure AI Search
await ductape.vector.create({
  name: 'Product Embeddings',
  tag: 'product-vectors',
  type: 'azure-search',
  dimensions: 1536,
  envs: [{
    slug: 'prd',
    cloud: 'prod_azure',
    instance: 'my-search-service',
    region: 'eastus',
  }],
});

See Cloud-linked components for the full tier reference and service matrix.

Configuration Fields

Field	Type	Required	Description
product	string	Yes	Product to associate the vector config with
name	string	Yes	Human-readable display name
tag	string	Yes	Unique identifier for the vector config
dbType	VectorDBType	Yes	Provider: PINECONE, QDRANT, WEAVIATE, MEMORY
dimensions	number	Yes	Vector dimensionality (e.g., 1536 for OpenAI ada-002)
metric	DistanceMetric	No	Distance metric: COSINE, EUCLIDEAN, DOT_PRODUCT
envs	array	Yes	Environment-specific configurations

Environment Configuration

Field	Type	Required	Description
slug	string	Yes	Environment identifier (e.g., dev, staging, prd)
endpoint	string	Yes*	Vector database endpoint URL
apiKey	string	Yes*	API key for authentication
cloud	string	No	Workspace cloud connection tag (imports/provisions OpenSearch or Azure AI Search)
instance	string	No	Cloud resource name when using cloud
region	string	No	Cloud region (for some providers)
index	string	Yes*	Index/collection name
namespace	string	No	Namespace for data isolation
options	object	No	Additional provider-specific options

*Required fields vary by provider

Step 4: Connect to the Vector Database

Before performing operations, connect to the vector database:

TypeScript

await ductape.vector.connect({ tag: 'product-vectors' });

Step 5: Store Your First Vectors

Insert vectors with metadata:

TypeScript

await ductape.vector.upsert({
  tag: 'product-vectors',
  vectors: [
    {
      id: 'prod-001',
      values: generateEmbedding('Wireless Bluetooth Headphones'),
      metadata: {
        name: 'Wireless Bluetooth Headphones',
        category: 'electronics',
        price: 79.99,
      },
    },
    {
      id: 'prod-002',
      values: generateEmbedding('Running Shoes'),
      metadata: {
        name: 'Running Shoes',
        category: 'sports',
        price: 129.99,
      },
    },
  ],
});

Step 6: Query for Similar Vectors

Find vectors similar to a query:

TypeScript

const results = await ductape.vector.query({
  tag: 'product-vectors',
  vector: generateEmbedding('audio equipment'),
  topK: 5,
  includeMetadata: true,
});

results.matches.forEach((match) => {
  console.log(`${match.id}: ${match.score}`);
  console.log(`  Name: ${match.metadata?.name}`);
});

Complete Example

TypeScript

import Ductape, { VectorDBType, DistanceMetric } from '@ductape/sdk';

async function main() {
  const ductape = new Ductape({
    accessKey: 'your-access-key',
  });

  // 1. Create vector configuration
  await ductape.vector.create({
    name: 'FAQ Embeddings',
    tag: 'faq-vectors',
    type: VectorDBType.QDRANT,
    dimensions: 1536,
    metric: DistanceMetric.COSINE,
    envs: [
      {
        slug: 'dev',
        endpoint: 'http://localhost:6333',
        index: 'faqs',
      },
    ],
  });

  // 2. Connect to the vector database
  await ductape.vector.connect({ tag: 'faq-vectors' });

  // 3. Store FAQs
  await ductape.vector.upsert({
    tag: 'faq-vectors',
    vectors: [
      {
        id: 'faq-1',
        values: await getEmbedding('How do I reset my password?'),
        metadata: {
          question: 'How do I reset my password?',
          answer: 'Click "Forgot Password" on the login page...',
          category: 'account',
        },
      },
      {
        id: 'faq-2',
        values: await getEmbedding('What payment methods do you accept?'),
        metadata: {
          question: 'What payment methods do you accept?',
          answer: 'We accept Visa, Mastercard, and PayPal...',
          category: 'billing',
        },
      },
    ],
  });

  // 4. Search for relevant FAQs
  const userQuestion = 'I forgot my login credentials';
  const results = await ductape.vector.query({
    tag: 'faq-vectors',
    vector: await getEmbedding(userQuestion),
    topK: 3,
    includeMetadata: true,
  });

  console.log('Most relevant FAQs:');
  results.matches.forEach((match, i) => {
    console.log(`${i + 1}. ${match.metadata?.question} (${match.score.toFixed(3)})`);
  });
}

// Helper function to generate embeddings (use your preferred provider)
async function getEmbedding(text: string): Promise<number[]> {
  // Use OpenAI, Cohere, or another embedding provider
  // Return array of numbers matching your dimensions
}

main().catch(console.error);

Provider-Specific Setup

Pinecone

TypeScript

import { VectorDBType, DistanceMetric } from '@ductape/sdk';

await ductape.vector.create({
  name: 'Pinecone Vectors',
  tag: 'pinecone-db',
  type: VectorDBType.PINECONE,
  dimensions: 1536,
  metric: DistanceMetric.COSINE,
  envs: [
    {
      slug: 'prd',
      endpoint: 'https://your-index-xxx.svc.pinecone.io',
      apiKey: process.env.PINECONE_API_KEY,
      index: 'your-index-name',
      namespace: 'production',
    },
  ],
});

Qdrant

TypeScript

import { VectorDBType, DistanceMetric } from '@ductape/sdk';

await ductape.vector.create({
  name: 'Qdrant Vectors',
  tag: 'qdrant-db',
  type: VectorDBType.QDRANT,
  dimensions: 1536,
  metric: DistanceMetric.COSINE,
  envs: [
    {
      slug: 'dev',
      endpoint: 'http://localhost:6333',  // Local Qdrant
      index: 'my-collection',
    },
    {
      slug: 'prd',
      endpoint: 'https://your-cluster.qdrant.io',
      apiKey: process.env.QDRANT_API_KEY,
      index: 'my-collection',
    },
  ],
});

Weaviate

TypeScript

import { VectorDBType, DistanceMetric } from '@ductape/sdk';

await ductape.vector.create({
  name: 'Weaviate Vectors',
  tag: 'weaviate-db',
  type: VectorDBType.WEAVIATE,
  dimensions: 1536,
  metric: DistanceMetric.COSINE,
  envs: [
    {
      slug: 'prd',
      endpoint: 'https://your-cluster.weaviate.network',
      apiKey: process.env.WEAVIATE_API_KEY,
      index: 'Documents',  // Class name in Weaviate
    },
  ],
});

In-Memory (Development/Testing)

TypeScript

import { VectorDBType, DistanceMetric } from '@ductape/sdk';

await ductape.vector.create({
  name: 'Memory Vectors',
  tag: 'memory-db',
  type: VectorDBType.MEMORY,
  dimensions: 1536,
  metric: DistanceMetric.COSINE,
  envs: [
    {
      slug: 'dev',
      index: 'test-collection',
    },
  ],
});

Common Embedding Dimensions

Model	Provider	Dimensions
text-embedding-ada-002	OpenAI	1536
text-embedding-3-small	OpenAI	1536
text-embedding-3-large	OpenAI	3072
embed-english-v3.0	Cohere	1024
voyage-02	Voyage AI	1024
all-MiniLM-L6-v2	Sentence Transformers	384

Next Steps

• Querying - Advanced query patterns and filters
• Metadata Filtering - Filter results by metadata
• Using with Agents - Connect vectors to AI agents
• Best Practices - Production patterns