Skip to content

Latest commit

 

History

History
263 lines (210 loc) · 7.24 KB

README.md

File metadata and controls

263 lines (210 loc) · 7.24 KB
Raw


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.