simple-example.ts

/**
 * Simple Example: Basic usage of seekdb with Embedding Functions
 *
 * This example demonstrates the most common operations with embedding functions:
 * 1. Create a client connection
 * 2. Create a collection with embedding function
 * 3. Add data using documents (embeddings auto-generated)
 * 4. Query using query texts (embeddings auto-generated)
 * 5. Print query results
 *
 * This is a minimal example to get you started quickly with embedding functions.
 */

import { SeekdbClient } from "seekdb";

async function main() {
  // ==================== Step 1: Create Client Connection ====================
  // You can use embedded mode, server mode, or OceanBase mode
  // For this example, we'll use embedded mode (you can change to server or OceanBase)

  // Option 1: Embedded mode (local seekdb)
  const client = new SeekdbClient({
    path: "./seekdb.db",
    database: "test",
  });

  // Option 2: Connecting to seekdb server or OceanBase
  // const client = new SeekdbClient({
  //   host: "127.0.0.1",
  //   port: 2881,
  //   database: "test",
  //   user: "root",
  //   password: "",
  //   // For OceanBase: add tenant: "sys" or your tenant.
  //   // tenant: "sys",
  // });

  // ==================== Step 2: Create a Collection with Embedding Function ====================
  // A collection is like a table that stores documents with vector embeddings
  const COLLECTION_NAME = "my_simple_collection";

  // Create collection with default embedding function
  // The embedding function will automatically convert documents to embeddings

  // Default embedding function is used if no embedding function is provided
  const collection = await client.getOrCreateCollection({
    name: COLLECTION_NAME,
  });

  console.log(
    `Created collection '${collection.name}' with dimension: ${collection.dimension}`
  );
  console.log(`Embedding function: ${collection.embeddingFunction?.name}`);

  // ==================== Step 3: Add Data to Collection ====================
  // With embedding function, you can add documents directly without providing embeddings
  // The embedding function will automatically generate embeddings from documents

  const documents = [
    "Machine learning is a subset of artificial intelligence",
    "Python is a popular programming language",
    "Vector databases enable semantic search",
    "Neural networks are inspired by the human brain",
    "Natural language processing helps computers understand text",
  ];

  const ids = ["id1", "id2", "id3", "id4", "id5"];

  // Add data with documents only - embeddings will be auto-generated by embedding function
  await collection.add({
    ids,
    documents, // embeddings will be automatically generated
    metadatas: [
      { category: "AI", index: 0 },
      { category: "Programming", index: 1 },
      { category: "Database", index: 2 },
      { category: "AI", index: 3 },
      { category: "NLP", index: 4 },
    ],
  });

  console.log(`\nAdded ${documents.length} documents to collection`);
  console.log(
    "Note: Embeddings were automatically generated from documents using the embedding function"
  );

  // ==================== Step 4: Query the Collection ====================
  // With embedding function, you can query using text directly
  // The embedding function will automatically convert query text to query vector

  // Query using text - query vector will be auto-generated by embedding function
  const queryText = "artificial intelligence and machine learning";

  const results = await collection.query({
    queryTexts: queryText, // Query text - will be embedded automatically
    nResults: 3, // Return top 3 most similar documents
    include: ["documents", "metadatas", "distances"],
  });

  const hitCount = results.ids?.[0]?.length ?? 0;
  console.log(`\nQuery: '${queryText}'`);
  console.log(`Query results: ${hitCount} items found`);

  // ==================== Step 5: Print Query Results ====================
  for (let i = 0; i < hitCount; i++) {
    console.log(`\nResult ${i + 1}:`);
    console.log(`  ID: ${results.ids?.[0]?.[i]}`);
    console.log(`  Distance: ${results.distances?.[0]?.[i]?.toFixed(4)}`);
    console.log(`  Document: ${results.documents?.[0]?.[i]}`);
    console.log(`  Metadata: ${JSON.stringify(results.metadatas?.[0]?.[i])}`);
  }

  // ==================== Step 6: Cleanup ====================
  await client.deleteCollection(COLLECTION_NAME);
  console.log(`\nCleaned up collection '${COLLECTION_NAME}'`);
  await client.close();
}

main().catch(console.error);