Migration Guide

// v2.x - Still works in v3.x
const db = await create({
  schema: {
    title: 'string',
    content: 'string'
  }
})

// v3.x - Enhanced with better types
const db = await create({
  schema: {
    title: 'string',
    content: 'string',
    embedding: 'vector[512]'  // Better vector support
  },
  plugins: [secureProxyPlugin]  // Enhanced plugin system
})

// v2.x - Mode was optional
const results = await search(db, {
  term: 'query'
})

// v3.x - Explicit modes for better clarity
const fullTextResults = await search(db, {
  mode: 'fulltext',  // Default, can be omitted
  term: 'query'
})

const vectorResults = await search(db, {
  mode: 'vector',
  vector: {
    value: embedding,
    property: 'embedding'
  }
})

const hybridResults = await search(db, {
  mode: 'hybrid',
  term: 'query',
  vector: {
    value: embedding,
    property: 'embedding'
  }
})

import { create, insertMultiple, AnswerSession } from '@orama/orama'
import { pluginSecureProxy } from '@orama/plugin-secure-proxy'

const secureProxy = await pluginSecureProxy({
  apiKey: 'my-api-key',
  defaultProperty: 'embeddings',
  models: {
    chat: 'openai/gpt-4o-mini'
  }
})

const db = await create({
  schema: {
    name: 'string',
    content: 'string'
  },
  plugins: [secureProxy]
})

await insertMultiple(db, documents)

// NEW in v3.x: RAG chat sessions
const session = new AnswerSession(db, {
  systemPrompt: 'You are a helpful assistant',
  events: {
    onStateChange: (state) => console.log('State:', state)
  }
})

const answer = await session.ask({ term: 'What is Orama?' })
console.log(answer)

// v3.x - More plugin hooks available
const plugin = {
  name: 'my-plugin',
  // New hooks in v3.x
  beforeInsert: async (orama, id, doc) => { },
  afterInsert: async (orama, id, doc) => { },
  afterInsertMultiple: async (orama, docs) => { },  // NEW
  beforeSearch: async (orama, params) => { },
  afterSearch: async (orama, results) => { },
  getComponents: (schema) => ({ })  // NEW
}

// v3.x - Better type inference
import { create, type TypedDocument } from '@orama/orama'

type Schema = {
  id: 'string'
  title: 'string'
  price: 'number'
}

const db = await create({
  schema: {
    id: 'string',
    title: 'string',
    price: 'number'
  } satisfies Schema
})

// TypeScript now infers the correct document type
const results = await search(db, { term: 'laptop' })
results.hits.forEach(hit => {
  // Fully typed!
  console.log(hit.document.title)  // string
  console.log(hit.document.price)  // number
})

// v2.x - Export your data
import { save } from '@orama/orama'

const serialized = await save(db)
await fs.writeFile('orama-v2-export.json', JSON.stringify(serialized))

// v3.x - Import your data
import { create, load } from '@orama/orama'
import fs from 'fs/promises'

// Create new v3.x database with same schema
const db = await create({
  schema: { /* same schema as v2.x */ }
})

// Load v2.x data
const data = JSON.parse(await fs.readFile('orama-v2-export.json', 'utf-8'))
load(db, data)

console.log('Migration complete!')

// v2.x
import { persistToLocalStorage } from '@orama/plugin-data-persistence'

// v3.x - Enhanced with more storage options
import { pluginPersistence } from '@orama/plugin-data-persistence'

const db = await create({
  schema: { /* ... */ },
  plugins: [
    pluginPersistence({
      storage: 'localStorage',  // or 'indexedDB', 'fileSystem'
      key: 'my-search-db'
    })
  ]
})

// v2.x
import { pluginEmbeddings } from '@orama/plugin-embeddings'

// v3.x - Same API, better performance
const plugin = await pluginEmbeddings({
  embeddings: {
    defaultProperty: 'embeddings',
    onInsert: {
      generate: true,
      properties: ['description'],
      verbose: true
    }
  }
})

import { create, insertMultiple, search, save, load } from '@orama/orama'
import assert from 'assert'

async function testMigration() {
  // Create test database
  const db = await create({
    schema: {
      id: 'string',
      title: 'string',
      content: 'string'
    }
  })
  
  // Insert test data
  const testDocs = [
    { id: '1', title: 'Test 1', content: 'Content 1' },
    { id: '2', title: 'Test 2', content: 'Content 2' }
  ]
  await insertMultiple(db, testDocs)
  
  // Test search
  const results = await search(db, { term: 'test' })
  assert.equal(results.count, 2, 'Should find 2 results')
  
  // Test serialization
  const serialized = await save(db)
  assert(serialized.index, 'Should have index data')
  assert(serialized.docs, 'Should have document data')
  
  // Test deserialization
  const db2 = await create({ schema: db.schema })
  load(db2, serialized)
  const results2 = await search(db2, { term: 'test' })
  assert.equal(results2.count, 2, 'Loaded DB should have same results')
  
  console.log('✅ Migration tests passed!')
}

testMigration().catch(console.error)

import { performance } from 'perf_hooks'

async function benchmark(db, queries) {
  const times = []
  
  for (const query of queries) {
    const start = performance.now()
    await search(db, { term: query, limit: 20 })
    times.push(performance.now() - start)
  }
  
  const avg = times.reduce((a, b) => a + b) / times.length
  console.log(`Average search time: ${avg.toFixed(2)}ms`)
  return avg
}

// Compare v2 vs v3
const v2Time = await benchmark(dbV2, testQueries)
const v3Time = await benchmark(dbV3, testQueries)
console.log(`Performance change: ${((v3Time - v2Time) / v2Time * 100).toFixed(1)}%`)