Skip to main content

​
What are Orama Plugins?

Orama’s plugin system allows you to extend and customize the behavior of your search instances with additional functionality. Plugins hook into Orama’s lifecycle events to modify data at insert time, enhance search queries, collect analytics, and more.

​
Available Plugins

Embeddings

Generate text embeddings offline for vector and hybrid search

Secure Proxy

Cloud-based embeddings and LLM features with secure API proxy

Analytics

Track and analyze search queries, results, and user behavior

Data Persistence

Serialize and restore Orama instances in multiple formats

Match Highlight

Highlight search matches in results (deprecated)

ParseDoc

Parse and index HTML/Markdown documentation files

​
How Plugins Work

Plugins implement hooks that are called at specific points in Orama’s lifecycle: 
import { create } from '@orama/orama'
import { myPlugin } from '@orama/plugin-example'

const db = await create({
  schema: {
    title: 'string',
    description: 'string'
  },
  plugins: [myPlugin({
    // Plugin configuration
  })]
})

​
Available Plugin Hooks

Orama provides the following lifecycle hooks for plugins:
  • beforeInsert - Called before inserting a document
  • afterInsert - Called after inserting a document
  • beforeInsertMultiple - Called before inserting multiple documents
  • afterInsertMultiple - Called after inserting multiple documents
  • beforeUpdate - Called before updating a document
  • afterUpdate - Called after updating a document
  • beforeUpdateMultiple - Called before updating multiple documents
  • afterUpdateMultiple - Called after updating multiple documents
  • beforeRemove - Called before removing a document
  • afterRemove - Called after removing a document
  • beforeRemoveMultiple - Called before removing multiple documents
  • afterRemoveMultiple - Called after removing multiple documents
  • beforeUpsert - Called before upserting a document
  • afterUpsert - Called after upserting a document
  • beforeUpsertMultiple - Called before upserting multiple documents
  • afterUpsertMultiple - Called after upserting multiple documents
  • beforeSearch - Called before performing a search
  • afterSearch - Called after performing a search
  • afterCreate - Called after creating an Orama instance
  • beforeLoad - Called before loading data into an instance
  • afterLoad - Called after loading data into an instance

​
Plugin Types

Orama supports both synchronous and asynchronous plugins:

​
Synchronous Plugins

import { OramaPluginSync } from '@orama/orama'

const mySyncPlugin: OramaPluginSync = {
  name: 'my-sync-plugin',
  afterInsert: (orama, id, doc) => {
    console.log('Document inserted:', id)
  }
}

​
Asynchronous Plugins

import { OramaPluginAsync } from '@orama/orama'

async function myAsyncPlugin(): Promise<OramaPluginAsync> {
  const model = await loadModel()
  
  return {
    name: 'my-async-plugin',
    beforeInsert: async (orama, id, doc) => {
      doc.embeddings = await model.embed(doc.text)
    }
  }
}

​
Using Multiple Plugins

You can use multiple plugins together. They will be executed in the order they are defined: 
import { create } from '@orama/orama'
import { pluginAnalytics } from '@orama/plugin-analytics'
import { pluginSecureProxy } from '@orama/plugin-secure-proxy'

const db = await create({
  schema: {
    title: 'string',
    description: 'string',
    embeddings: 'vector[384]'
  },
  plugins: [
    pluginSecureProxy({
      apiKey: 'your-api-key',
      embeddings: {
        defaultProperty: 'embeddings',
        model: 'orama/gte-small',
        onInsert: {
          generate: true,
          properties: ['title', 'description']
        }
      }
    }),
    pluginAnalytics({
      apiKey: 'your-api-key',
      indexId: 'your-index-id'
    })
  ]
})

​
Next Steps

Write Custom Plugins

Learn how to create your own Orama plugins

Explore Official Plugins

Browse available official plugins

Build docs developers (and LLMs) love

Get started for freeTalk to us