Skip to content

oramasearch/orama

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
March 21, 2023 17:49
March 21, 2023 17:49
March 21, 2023 17:49
June 15, 2023 11:48
May 10, 2022 14:27
March 21, 2023 17:49
March 21, 2023 17:49
March 21, 2023 17:49


Website β€’ Blog β€’ Documentation β€’ Slack


A resilient, innovative and open-source full-text and vector search experience to achieve
seamless integration with your infrastructure and data


Tests npm bundle size Open Bounties Rewarded Bounties

Join Orama's Slack channel

If you need more info, help, or want to provide general feedback on Orama, join the Orama Slack channel

Highlighted features

Installation

You can install Orama using npm, yarn, pnpm:

npm i @orama/orama
yarn add @orama/orama
pnpm add @orama/orama

Or import it directly in a browser module:

<html>
  <body>
    <script type="module">
      import { create, search, insert } from 'https://unpkg.com/@orama/orama@latest/dist/index.js'

      // ...
    </script>
  </body>
</html>

Read the complete documentation at https://docs.oramasearch.com.

Usage

Orama is quite simple to use. The first thing to do is to create a new database instance and set an indexing schema:

import { create, insert, remove, search, searchVector } from '@orama/orama'

const db = await create({
  schema: {
    name: 'string',
    description: 'string',
    price: 'number',
    embedding: 'vector[1536]', // Vector size must be expressed during schema initialization
    meta: {
      rating: 'number',
    },
  },
})

If you are using Node.js without ESM, please see the usage with CommonJS section below on how to properly require Orama.

Orama will only index string properties, but will allow you to set and store additional data if needed.

Once the db instance is created, you can start adding some documents:

await insert(db, {
  name: 'Wireless Headphones',
  description: 'Experience immersive sound quality with these noise-cancelling wireless headphones.',
  price: 99.99,
  embedding: [...],
  meta: {
    rating: 4.5,
  },
})

await insert(db, {
  name: 'Smart LED Bulb',
  description: 'Control the lighting in your home with this energy-efficient smart LED bulb, compatible with most smart home systems.',
  price: 24.99,
  embedding: [...],
  meta: {
    rating: 4.3,
  },
})

await insert(db, {
  name: 'Portable Charger',
  description: 'Never run out of power on-the-go with this compact and fast-charging portable charger for your devices.',
  price: 29.99,
  embedding: [...],
  meta: {
    rating: 3.6,
  },
})

After the data has been inserted, you can finally start to query the database.

const searchResult = await search(db, {
  term: 'headphones',
})

In the case above, you will be searching for all the documents containing the word headphones, looking up in every schema property (AKA index):

{
  elapsed: {
    raw: 99512,
    formatted: '99ΞΌs',
  },
  hits: [
    {
      id: '41013877-56',
      score: 0.925085832971998432,
      document: {
        name: 'Wireless Headphones',
        description: 'Experience immersive sound quality with these noise-cancelling wireless headphones.',
        price: 99.99,
        meta: {
          rating: 4.5
        }
      }
    }
  ],
  count: 1
}

You can also restrict the lookup to a specific property:

const searchResult = await search(db, {
  term: 'immersive sound quality',
  properties: ['description'],
})

Result:

{
  elapsed: {
    raw: 21492,
    formatted: '21ΞΌs',
  },
  hits: [
    {
      id: '41013877-56',
      score: 0.925085832971998432,
      document: {
        name: 'Wireless Headphones',
        description: 'Experience immersive sound quality with these noise-cancelling wireless headphones.',
        price: 99.99,
        meta: {
          rating: 4.5
        }
      }
    }
  ],
  count: 1
}

If you want to perform a vector search, you can use the searchVector function:

const searchResult = await searchVector(db, {
  vector: [...], // OpenAI embedding or similar vector to be used as an input
  property: 'embedding' // Property to search through. Mandatory for vector search
})

Usage with CommonJS

Orama is packaged as ES modules, suitable for Node.js, Deno, Bun and modern browsers.

In most cases, simply import or @orama/orama will suffice ✨.

In Node.js, when not using ESM (with "type": "module" in the package.json), you have several ways to properly require Orama. Starting with version 0.4.0 it becomes:

async function main() {
  const { create, insert } = await import('@orama/orama')

  const db = create(/* ... */)
  insert(db, {
    /* ... */
  })
}

main().catch(console.error)

Use CJS requires

Orama methods can be required as CommonJS modules by requiring from @orama/orama.

const { create, insert } = require("@orama/orama")

create(/* ... */)
  .then(db => insert(db, { /* ... */ })
  .catch(console.error)

Note that only main methods are supported so for internals and other supported exports you still have to use await import.

Community Rewards

Orama Community Rewards

Are you using Orama in production? Have you written an article or made a YouTube video on Orama? Contact us to get some Orama swag in return!

Official Docs

Read the complete documentation at https://docs.oramasearch.com.

License

Orama is licensed under the Apache 2.0 license.