Vector Database

Overview

Vector Database - Store and search content using AI-powered vector embeddings. Enables semantic search, similarity matching, and intelligent content discovery with automatic embedding generation and smart chunking.

Operations

An operation is an action performed on the vector database. All operations require the op property to specify which operation to perform.

Operation	Description
`vdb.insert`	Insert content with automatic embeddings
`vdb.search`	Semantic similarity search
`vdb.delete`	Delete vector entries

Insert Vectors

vdb.insert

Insert content into the vector database with automatic embedding generation.

Basic text insert:

json

{
  "op": "vdb.insert",
  "collection": "knowledge_base",
  "data": [
    {
      "content": "Artificial intelligence is transforming how businesses operate by automating complex processes.",
      "content_type": "text",
      "metadata": {
        "document_id": "doc_001",
        "source": "company_wiki",
        "tags": ["AI", "automation"]
      }
    }
  ]
}

With custom chunking:

json

{
  "op": "vdb.insert",
  "collection": "documentation",
  "data": [
    {
      "content": "# Machine Learning Guide\n\nThis guide covers best practices...",
      "content_type": "markdown",
      "filename": "ml-guide.md",
      "metadata": {
        "category": "guides",
        "tags": ["ML", "best-practices"]
      }
    }
  ],
  "options": {
    "chunk_size": 500,
    "chunk_overlap": 50
  }
}

Parameters:

collection (required) - Collection name for vector storage
data (required) - Array of content objects to embed
- content (required) - Text content to embed and store
- content_type (optional) - Format: text, json, markdown, html (default: text)
- filename (optional) - Associated filename
- metadata (optional) - Custom metadata for filtering
options (optional):
- chunk_size - Max characters per chunk (default: 500)
- chunk_overlap - Character overlap between chunks (default: 40)

Response:

json

{
  "data": [
    {
      "_key": "vec_abc123xyz789",
      "content": "Artificial intelligence is transforming...",
      "is_chunked": false,
      "metadata": {
        "document_id": "doc_001",
        "source": "company_wiki",
        "tags": ["AI", "automation"]
      }
    }
  ]
}

Response fields:

_key - Unique vector identifier
content - Original content
is_chunked - Whether content was split into chunks
metadata - Associated metadata

Search Vectors

vdb.search

Perform semantic similarity search using natural language queries.

Basic search:

json

{
  "op": "vdb.search",
  "query": "How does machine learning improve business processes?",
  "collection": "knowledge_base"
}

Search with filename filter:

json

{
  "op": "vdb.search",
  "query": "API authentication best practices",
  "collection": "documentation",
  "filename": "auth-guide.md"
}

Parameters:

query (required) - Natural language search query
collection (optional) - Specific collection to search
filename (optional) - Filter by filename

Response:

json

{
  "data": [
    {
      "_key": "vec_abc123",
      "content": "Machine learning algorithms can automate complex business processes...",
      "is_chunked": false,
      "similarity_score": 0.92,
      "metadata": {
        "document_id": "doc_002",
        "source": "documentation",
        "tags": ["ML", "automation"],
        "filename": "ml-guide.md"
      }
    },
    {
      "_key": "vec_def456",
      "content": "Artificial intelligence transforms business operations...",
      "is_chunked": true,
      "similarity_score": 0.87,
      "metadata": {
        "document_id": "doc_001",
        "tags": ["AI", "business"]
      }
    }
  ],
  "meta": {
    "query": "How does machine learning improve business processes?",
    "total_results": 2,
    "search_time_ms": 45
  }
}

Response fields:

similarity_score - Cosine similarity (0.0 to 1.0, higher is more similar)
content - Matched content
metadata - Associated metadata including tags and source

Delete Vectors

vdb.delete

Remove vector entries from the database.

json

{
  "op": "vdb.delete",
  "collection": "knowledge_base",
  "_keys": [
    "vec_abc123xyz789",
    "vec_def456uvw012"
  ]
}

Parameters:

collection (required) - Collection containing vectors
_keys (required) - Array of vector keys to delete

Response:

json

{
  "data": {
    "deleted_count": 2,
    "deleted_keys": [
      "vec_abc123xyz789",
      "vec_def456uvw012"
    ]
  }
}

Content Processing

Automatic Chunking

Large content is automatically split into chunks for optimal embedding:

Default chunk size: 500 characters
Default overlap: 40 characters
Context preserved across boundaries
Metadata maintained for all chunks

Chunking strategies:

Small chunks (200-400):

Better for precise fact retrieval
Higher granularity
More chunks per document

Large chunks (800-1200):

Better for contextual understanding
More complete information
Better for narrative content

Content Types

text - Plain text, processed as-is
markdown - Headers and structure preserved
html - Tags stripped, text extracted
json - Structured data flattened

Common Use Cases

Knowledge Base Search

javascript

// Insert documentation
await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key',
    'Authorization': 'Bearer your_jwt_token'
  },
  body: JSON.stringify({
    op: 'vdb.insert',
    collection: 'company_docs',
    data: [
      {
        content: 'Employee remote work policy: All employees may work remotely...',
        content_type: 'text',
        metadata: {
          document_id: 'policy_remote',
          category: 'HR',
          tags: ['remote', 'policy']
        }
      }
    ]
  })
});

// Search documentation
const results = await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key',
    'Authorization': 'Bearer your_jwt_token'
  },
  body: JSON.stringify({
    op: 'vdb.search',
    query: 'Can I work from home?',
    collection: 'company_docs'
  })
});

Chatbot Integration

javascript

async function answerQuestion(userQuestion) {
  // Search knowledge base
  const response = await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'your_api_key',
      'Authorization': 'Bearer your_jwt_token'
    },
    body: JSON.stringify({
      op: 'vdb.search',
      query: userQuestion,
      collection: 'support_kb'
    })
  });

  const results = await response.json();
  
  // Use top results for context
  const context = results.data
    .slice(0, 3)
    .map(r => r.content)
    .join('\n\n');
    
  return generateResponse(userQuestion, context);
}

Best Practices

Content Organization

Use descriptive collection names by domain (e.g., support_articles, product_docs)
Implement consistent tagging strategies
Include relevant metadata for filtering
Regularly cleanup outdated vectors

Search Optimization

Frame queries as natural questions for better results
Use specific terminology for technical content
Combine vector search with metadata filtering
Monitor search patterns to optimize chunking

Metadata Strategy

Good metadata structure:

json

{
  "metadata": {
    "category": "technical",
    "subcategory": "api",
    "difficulty": "intermediate",
    "last_updated": "2024-01-15",
    "tags": ["authentication", "security"]
  }
}

Performance

Batch insert operations when adding multiple documents
Use appropriate chunk sizes for your content type
Implement caching for frequent queries
Monitor storage usage and optimize retention

Error Handling

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Common error codes:

INVALID_CONTENT - Content empty or exceeds max length (50,000 chars)
COLLECTION_NOT_FOUND - Collection doesn't exist
VECTOR_NOT_FOUND - Vector key doesn't exist
EMBEDDING_FAILED - Vector generation failed
QUOTA_EXCEEDED - Storage quota reached

Complete Example

javascript

// 1. Insert documents
const insertResponse = await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key',
    'Authorization': 'Bearer your_jwt_token'
  },
  body: JSON.stringify({
    op: 'vdb.insert',
    collection: 'docs',
    data: [
      {
        content: 'Machine learning enables computers to learn from data without explicit programming.',
        content_type: 'text',
        metadata: {
          topic: 'ML',
          difficulty: 'beginner'
        }
      },
      {
        content: 'Neural networks are computational models inspired by the human brain.',
        content_type: 'text',
        metadata: {
          topic: 'ML',
          difficulty: 'intermediate'
        }
      }
    ],
    options: {
      chunk_size: 300,
      chunk_overlap: 30
    }
  })
});

const insertData = await insertResponse.json();
console.log('Inserted vectors:', insertData.data.map(v => v._key));

// 2. Search
const searchResponse = await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key',
    'Authorization': 'Bearer your_jwt_token'
  },
  body: JSON.stringify({
    op: 'vdb.search',
    query: 'What is machine learning?',
    collection: 'docs'
  })
});

const searchData = await searchResponse.json();
console.log('Search results:');
searchData.data.forEach(result => {
  console.log(`Score: ${result.similarity_score}, Content: ${result.content}`);
});

// 3. Delete old vectors
await fetch('https://cloud.singlebaseapis.com/api/<ENDPOINT_KEY>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your_api_key',
    'Authorization': 'Bearer your_jwt_token'
  },
  body: JSON.stringify({
    op: 'vdb.delete',
    collection: 'docs',
    _keys: ['vec_old_123', 'vec_old_456']
  })
});

Semantic Search Features

Natural language queries:

Ask questions in plain English
Contextual understanding
Fuzzy matching for typos

Use cases:

Question answering systems
Document search and discovery
Customer support automation
Content recommendations
Research paper discovery
Chatbot knowledge bases

Vector Database ​

Overview ​

Operations ​

Insert Vectors ​

vdb.insert ​

Search Vectors ​

vdb.search ​

Delete Vectors ​

vdb.delete ​

Content Processing ​

Automatic Chunking ​

Content Types ​

Common Use Cases ​

Knowledge Base Search ​

Chatbot Integration ​

Similar Content Recommendation ​

Best Practices ​

Content Organization ​

Search Optimization ​

Metadata Strategy ​

Performance ​

Error Handling ​

Complete Example ​

Semantic Search Features ​

Vector Database

Overview

Operations

Insert Vectors

vdb.insert

Search Vectors

vdb.search

Delete Vectors

vdb.delete

Content Processing

Automatic Chunking

Content Types

Common Use Cases

Knowledge Base Search

Chatbot Integration

Similar Content Recommendation

Best Practices

Content Organization

Search Optimization

Metadata Strategy

Performance

Error Handling

Complete Example

Semantic Search Features