Lyra

Fast, in-memory, typo-tolerant, full-text search engine written in TypeScri...

README

Join Orama's Slack channel


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

Installation


You can install Orama using npm, yarn, pnpm:

  1. ```sh
  2. npm i @orama/orama
  3. ```

  1. ```sh
  2. yarn add @orama/orama
  3. ```

  1. ```sh
  2. pnpm add @orama/orama
  3. ```

Or import it directly in a browser module:

  1. ```html
  2. <html>
  3.   <body>
  4.     <script type="module">
  5.       import { create, search, insert } from 'https://unpkg.com/@orama/orama@latest/dist/index.js'
  6.       // ...
  7.     </script>
  8.   </body>
  9. </html>
  10. ```

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:

  1. ```js
  2. import { create, insert, remove, search } from '@orama/orama'

  3. const db = await create({
  4.   schema: {
  5.     author: 'string',
  6.     quote: 'string',
  7.   },
  8. })
  9. ```

If you are using Node.js without ESM, please see build 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:

  1. ```js
  2. await insert(db, {
  3.   quote: 'It is during our darkest moments that we must focus to see the light.',
  4.   author: 'Aristotle',
  5. })

  6. await insert(db, {
  7.   quote: 'If you really look closely, most overnight successes took a long time.',
  8.   author: 'Steve Jobs',
  9. })

  10. await insert(db, {
  11.   quote: 'If you are not willing to risk the usual, you will have to settle for the ordinary.',
  12.   author: 'Jim Rohn',
  13. })

  14. await insert(db, {
  15.   quote: "You miss 100% of the shots you don't take",
  16.   author: 'Wayne Gretzky - Michael Scott',
  17. })
  18. ```

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

  1. ```js
  2. const searchResult = await search(db, {
  3.   term: 'if',
  4.   properties: '*',
  5.   boost: {
  6.     author: 1.5, // optional: boost author field by x1.5
  7.   },
  8. })
  9. ```

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

  1. ```js
  2. {
  3.   elapsed: {
  4.     raw: 184541,
  5.     formatted: '184μs',
  6.   },
  7.   hits: [
  8.     {
  9.       id: '41013877-56',
  10.       score: 0.025085832971998432,
  11.       document: {
  12.         quote: 'If you really look closely, most overnight successes took a long time.',
  13.         author: 'Steve Jobs'
  14.       }
  15.     },
  16.     {
  17.       id: '41013877-107',
  18.       score: 0.02315615351261394,
  19.       document: {
  20.         quote: 'If you are not willing to risk the usual, you will have to settle for the ordinary.',
  21.         author: 'Jim Rohn'
  22.       }
  23.     }
  24.   ],
  25.   count: 2
  26. }
  27. ```

You can also restrict the lookup to a specific property:

  1. ```js
  2. const searchResult = await search(db, {
  3.   term: 'Michael',
  4.   properties: ['author'],
  5. })
  6. ```

Result:

  1. ```js
  2. {
  3.   elapsed: {
  4.     raw: 172166,
  5.     formatted: '172μs',
  6.   },
  7.   hits: [
  8.     {
  9.       id: '41045799-144',
  10.       score: 0.12041199826559248,
  11.       document: {
  12.         quote: "You miss 100% of the shots you don't take",
  13.         author: 'Wayne Gretzky - Michael Scott'
  14.       }
  15.     }
  16.   ],
  17.   count: 1
  18. }
  19. ```

If needed, you can also delete a given document by using the remove method:

  1. ```js
  2. await remove(db, '41045799-144')
  3. ```

Using 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:

  1. ```js
  2. async function main() {
  3.   const { create, insert } = await import('@orama/orama')

  4.   const db = create(/* ... */)
  5.   insert(db, {
  6.     /* ... */
  7.   })
  8. }

  9. main().catch(console.error)
  10. ```

Use CJS requires


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

  1. ```js
  2. const { create, insert } = require("@orama/orama")

  3. create(/* ... */)
  4.   .then(db => insert(db, { /* ... */ })
  5.   .catch(console.error)
  6. ```

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

Language


Orama supports multiple languages. By default, it will use the english
language,

You can specify a different language by using the defaultLanguage property
during Orama initialization.

By default, Orama will analyze your input using an English
[Porter Stemmer](https://tartarus.org/martin/PorterStemmer/) function.
You can replace the default stemmer with a custom one, or a pre-built one
shipped with the default Orama installation.

Example:

  1. ```js
  2. import { create } from '@orama/orama'
  3. import { stemmer } from '@orama/orama/stemmers/it'

  4. const db = await create({
  5.   schema: {
  6.     author: 'string',
  7.     quote: 'string',
  8.   },
  9.   language: 'italian',
  10.   components: {
  11.     tokenizer: {
  12.       stemmingFn: stemmer,
  13.     },
  14.   },
  15. })
  16. ```

Example using CJS (see using with commonJS above):

  1. ```js
  2. async function main() {
  3.   const { create } = await import('@orama/orama')
  4.   const { stemmer } = await import('@orama/orama/stemmers/it')

  5.   const db = await create({
  6.     schema: {
  7.       author: 'string',
  8.       quote: 'string',
  9.     },
  10.     language: 'italian',
  11.     components: {
  12.       tokenizer: {
  13.         stemmingFn: stemmer,
  14.       },
  15.     },
  16.   })
  17. }

  18. main()
  19. ```

Right now, Orama supports 26 languages and stemmers out of the box:

- Arabic
- Armenian
- Bulgarian
- Danish
- Dutch
- English
- Finnish
- French
- German
- Greek
- Hindi
- Hungarian
- Indonesian
- Irish
- Italian
- Nepali
- Norwegian
- Portuguese
- Romanian
- Russian
- Serbian
- Slovenian
- Spanish
- Swedish
- Turkish
- Ukrainian

Official Docs


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

License


Orama is licensed under the Apache 2.0 license.