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.

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​

npm install @ductape/sdk@0.1.8

Step 2: Initialize the SDK​

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:

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:

const tiers = await ductape.cloud.tiers.list({ provider: 'aws', resource_type: 'vector' });
// 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​

FieldTypeRequiredDescription
productstringYesProduct to associate the vector config with
namestringYesHuman-readable display name
tagstringYesUnique identifier for the vector config
dbTypeVectorDBTypeYesProvider: PINECONE, QDRANT, WEAVIATE, MEMORY
dimensionsnumberYesVector dimensionality (e.g., 1536 for OpenAI ada-002)
metricDistanceMetricNoDistance metric: COSINE, EUCLIDEAN, DOT_PRODUCT
envsarrayYesEnvironment-specific configurations

Environment Configuration​

FieldTypeRequiredDescription
slugstringYesEnvironment identifier (e.g., dev, staging, prd)
endpointstringYes*Vector database endpoint URL
apiKeystringYes*API key for authentication
cloudstringNoWorkspace cloud connection tag (imports/provisions OpenSearch or Azure AI Search)
instancestringNoCloud resource name when using cloud
regionstringNoCloud region (for some providers)
indexstringYes*Index/collection name
namespacestringNoNamespace for data isolation
optionsobjectNoAdditional provider-specific options

*Required fields vary by provider

Step 4: Connect to the Vector Database​

Before performing operations, connect to the vector database:

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

Step 5: Store Your First Vectors​

Insert vectors with metadata:

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:

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​

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​

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​

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​

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)​

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​

ModelProviderDimensions
text-embedding-ada-002OpenAI1536
text-embedding-3-smallOpenAI1536
text-embedding-3-largeOpenAI3072
embed-english-v3.0Cohere1024
voyage-02Voyage AI1024
all-MiniLM-L6-v2Sentence Transformers384

Next Steps​