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.

``bash
npm install seekdb @seekdb/default-embed
`

Quick Start

`typescript
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.

$3

`typescript
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",
});
`

$3

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

`bash
npm install @seekdb/default-embed
`

`typescript
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:

`bash
npm install @seekdb/qwen
`

`typescript
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.

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

$3

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

`typescript
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.

`typescript
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],
],
});
`

$3

Get Data

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

`typescript
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.

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

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

`typescript
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.

`typescript
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.

`typescript
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,
});
`

$3

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:

`bash
npm install @seekdb/default-embed
`

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

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

#### Qwen Embedding

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

`bash
npm install @seekdb/qwen
`

`typescript
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.

`bash
npm install @seekdb/openai
`

`typescript
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.

`bash
npm install @seekdb/jina
`

`typescript
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:

`typescript
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 {
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:

`typescript
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,
});
`

$3

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

`typescript
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");
``