Vector database SDK for JavaScript/TypeScript with built-in semantic search Works seamlessly with seekdb and OceanBase

For complete usage, please refer to the official documentation.

Table of contents

Why seekdb? Installation Quick Start Usage Guide

Why seekdb?

• Auto Vectorization - Automatic embedding generation, no manual vector calculation needed
• Semantic Search - Vector-based similarity search for natural language queries
• Hybrid Search - Combine keyword matching with semantic search
• Multiple Embedding Functions - Built-in support for local and cloud embedding providers
• TypeScript Native - Full TypeScript support with complete type definitions

Installation

Before using the SDK, you need to deploy seekdb. Please refer to the official deployment documentation.

npm install seekdb @seekdb/default-embed

Quick Start

import { SeekdbClient } from "seekdb";

// 1. Connect
const client = new SeekdbClient({
  host: "127.0.0.1",
  port: 2881,
  user: "root",
  password: "",
  database: "test",
});

// 2. Create collection
const collection = await client.createCollection({ name: "my_collection" });

// 3. Add data (auto-vectorized using @seekdb/default-embed)
await collection.add({
  ids: ["1", "2"],
  documents: ["Hello world", "seekdb is fast"],
});

// 4. Search
const results = await collection.query({
  queryTexts: "Hello",
  nResults: 5,
});

console.log("query results", results);

Usage Guide

This section shows the most basic usage. For details, please refer to the official SDK documentation.

Client Connection

import { SeekdbClient } from "seekdb";

const client = new SeekdbClient({
  host: "127.0.0.1",
  port: 2881,
  user: "root",
  password: "",
  database: "test",
  // Required for OceanBase mode
  // tenant: "sys",
});

Create Collection

If you don't specify an embedding function, the default embedding function will be used for vectorization. Please install @seekdb/default-embed.

npm install @seekdb/default-embed

const collection = await client.createCollection({
  name: "my_collection",
});

If you need to use a specific embedding function, you can install and use the embedding functions we provide, or implement your own. For details, please refer to the official SDK documentation.

Take @seekdb/qwen as an example:

npm install @seekdb/qwen

import { QwenEmbeddingFunction } from "@seekdb/qwen";

const qwenEF = new QwenEmbeddingFucntion();
const collection = await client.createCollection({
  name: "my_collection",
  embeddingFunction: qwenEF,
});

If you don't need an embedding function, set embeddingFunction to null.

const collection = await client.createCollection({
  name: "my_collection",
  embeddingFunction: null,
});

Add Data

The embedding function defined in createCollection is used automatically for vectorization. No need to set it again.

await collection.add({
  ids: ["1", "2"],
  documents: ["Hello world", "seekdb is fast"],
  metadatas: [{ category: "test" }, { category: "db" }],
});

You can also pass a vector or an array of vectors directly.

const qwenEF = new QwenEmbeddingFucntion();
await collection.add({
  ids: ["1", "2"],
  documents: ["Hello world", "seekdb is fast"],
  metadatas: [{ category: "test" }, { category: "db" }],
  embeddings: [
    [0.1, 0.2, 0.3],
    [0.2, 0.3, 0.4],
  ],
});

Query Data

Get Data

The get() method is used to retrieve documents from a collection without performing vector similarity search.

const results = await collection.get({
  ids: ["1", "2"],
});

Semantic Search

The query() method is used to execute vector similarity search to find documents most similar to the query vector.

The embedding function defined in createCollection is used automatically for vectorization. No need to set it again.

const results = await collection.query({
  queryTexts: "Hello",
  nResults: 5,
});

You can also pass a vector or an array of vectors directly.

const results = await collection.query({
  queryEmbeddings: [
    [0.1, 0.2, 0.3],
    [0.2, 0.3, 0.4],
  ],
  nResults: 5,
});

Hybrid Search (Keyword + Semantic)

The hybridSearch() combines full-text search and vector similarity search with ranking.

const hybridResults = await collection.hybridSearch({
  query: { whereDocument: { $contains: "seekdb" } },
  knn: { queryTexts: ["fast database"] },
  nResults: 5,
});

You can also pass a vector or an array of vectors directly.

const hybridResults = await collection.hybridSearch({
  query: { whereDocument: { $contains: "seekdb" } },
  knn: {
    queryEmbeddings: [
      [0.1, 0.2, 0.3],
      [0.2, 0.3, 0.4],
    ],
  },
  nResults: 5,
});

Embedding Functions

The SDK supports multiple Embedding Functions for generating vectors locally or in the cloud.

For complete usage, please refer to the official documentation.

Default Embedding

Uses a local model (Xenova/all-MiniLM-L6-v2) by default. No API Key required. Suitable for quick development and testing.

No configuration is needed to use the default model.

First install the built-in model:

npm install @seekdb/default-embed

Then use it as-is; it will auto-vectorize:

const collection = await client.createCollection({
  name: "local_embed_collection",
});

Qwen Embedding

Uses DashScope's cloud Embedding service (Qwen/Tongyi Qianwen). Suitable for production environments.

npm install @seekdb/qwen

import { QwenEmbeddingFunction } from "@seekdb/qwen";

const qwenEmbed = new QwenEmbeddingFunction({
  // Your DashScope environment variable name, defaults to 'DASHSCOPE_API_KEY'
  apiKeyEnvVar: 'DASHSCOPE_API_KEY'
  // Optional, defaults to 'text-embedding-v4'
  modelName: "text-embedding-v4",
});

const collection = await client.createCollection({
  name: "qwen_embed_collection",
  embeddingFunction: qwenEmbed,
});

OpenAI Embedding

Uses OpenAI's embedding API. Suitable for production environments with OpenAI integration.

npm install @seekdb/openai

import { OpenAIEmbeddingFunction } from "@seekdb/openai";

const openaiEmbed = new OpenAIEmbeddingFunction({
  // Your openai environment variable name, defaults to 'OPENAI_API_KEY'
  apiKeyEnvVar: 'OPENAI_API_KEY'
  // Optional, defaults to 'text-embedding-3-small'
  modelName: "text-embedding-3-small",
});

const collection = await client.createCollection({
  name: "openai_embed_collection",
  embeddingFunction: openaiEmbed,
});

Jina Embedding

Uses Jina AI's embedding API. Supports multimodal embeddings.

npm install @seekdb/jina

import { JinaEmbeddingFunction } from "@seekdb/jina";

const jinaEmbed = new JinaEmbeddingFunction({
  // Your jina environment variable name, defaults to 'JINA_API_KEY'
  apiKeyEnvVar: 'JINA_API_KEY'
  // Optional, defaults to jina-clip-v2
  modelName: "jina-clip-v2",
});

const collection = await client.createCollection({
  name: "jina_embed_collection",
  embeddingFunction: jinaEmbed,
});

Custom Embedding Function

You can also use your own custom embedding function.

First, implement the EmbeddingFunction interface:

import type { EmbeddingFunction } from "seekdb";
import { registerEmbeddingFunction } from "seekdb";

interface MyCustomEmbeddingConfig {
  apiKeyEnv: string;
}
class MyCustomEmbeddingFunction implements EmbeddingFunction {
  // The name of the `embeddingFunction`, must be unique.
  readonly name = "my_custom_embedding";
  private apiKeyEnv: string;
  dimension: number;
  constructor(config: MyCustomEmbeddingConfig) {
    this.apiKeyEnv = config.apiKeyEnv;
    this.dimension = 384;
  }
  // Implement your vector generation code here
  async generate(texts: string[]): Promise<number[][]> {
    const embeddings: number[][] = [];
    return embeddings;
  }
  // The configuration of the current `embeddingFunction` instance, used to restore this instance
  getConfig(): MyCustomEmbeddingConfig {
    return {
      apiKeyEnv: this.apiKeyEnv,
    };
  }
  // Create a new instance of the current `embeddingFunction` based on the provided configuration
  static buildFromConfig(config: MyCustomEmbeddingConfig): EmbeddingFunction {
    return new MyCustomEmbeddingFunction(config);
  }
}

// Register the constructor
registerEmbeddingFunction("my_custom_embedding", MyCustomEmbeddingFunction);

Then use it:

const customEmbed = new MyCustomEmbeddingFunction({
  apiKeyEnv: "MY_CUSTOM_API_KEY_ENV",
});
const collection = await client.createCollection({
  name: "custom_embed_collection",
  configuration: {
    dimension: 384,
    distance: "cosine",
  },
  embeddingFunction: customEmbed,
});

Database Management

The SeekdbAdminClient allows you to manage databases (create, list, delete).

import { SeekdbAdminClient } from "seekdb";

const adminClient = new SeekdbAdminClient({
  host: "127.0.0.1",
  port: 2881,
  user: "root",
  password: "",
  // Required for OceanBase mode
  // tenant: "sys"
});

// Create a new database
await adminClient.createDatabase("new_database");

// List all databases
const databases = await adminClient.listDatabases();

// Get database info
const db = await adminClient.getDatabase("new_database");

// Delete a database
await adminClient.deleteDatabase("new_database");