diff --git a/package.json b/package.json index 06b278c19..5fcd0aa86 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "orama-monorepo", - "version": "2.0.0", + "version": "2.0.1", "description": "Next generation full-text and vector search engine, written in TypeScript", "workspaces": [ "packages/*", diff --git a/packages/benchmarks/package.json b/packages/benchmarks/package.json index fc8d227ed..eba6ade76 100644 --- a/packages/benchmarks/package.json +++ b/packages/benchmarks/package.json @@ -1,6 +1,6 @@ { "name": "benchmarks", - "version": "2.0.0", + "version": "2.0.1", "private": true, "scripts": { "bench:group": "node src/group.bench.js", diff --git a/packages/docs/package.json b/packages/docs/package.json index 013cc56db..1baa29b7a 100644 --- a/packages/docs/package.json +++ b/packages/docs/package.json @@ -1,6 +1,6 @@ { "name": "@orama/docs", - "version": "2.0.0", + "version": "2.0.1", "description": "Documentation for Orama", "private": true, "type": "module", diff --git a/packages/orama/README.md b/packages/orama/README.md index a8056db89..b1ec7299f 100644 --- a/packages/orama/README.md +++ b/packages/orama/README.md @@ -1,43 +1,40 @@ # Orama -Search, everywhere. +Full-text, vector, and hybrid search with a unique API.
+On your browser, server, mobile app, or at the edge.
+In less than 2kb. [![Tests](https://github.com/oramasearch/orama/actions/workflows/turbo.yml/badge.svg)](https://github.com/oramasearch/orama/actions/workflows/turbo.yml) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40orama%2Forama?label=Bundle%20Size&link=https%3A%2F%2Fbundlephobia.com%2Fpackage%2F%40orama%2Forama%40latest) -[![Open Bounties](https://img.shields.io/endpoint?url=https%3A%2F%2Fconsole.algora.io%2Fapi%2Fshields%2Foramasearch%2Fbounties%3Fstatus%3Dopen)](https://console.algora.io/org/oramasearch/bounties?status=open) -[![Rewarded Bounties](https://img.shields.io/endpoint?url=https%3A%2F%2Fconsole.algora.io%2Fapi%2Fshields%2Foramasearch%2Fbounties%3Fstatus%3Dcompleted)](https://console.algora.io/org/oramasearch/bounties?status=completed) # Join Orama's Slack channel -If you need more info, help, or want to provide general feedback on Orama, join the [Orama Slack channel](https://orama.to/slack) +If you need more info, help, or want to provide general feedback on Orama, join +the +[Orama Slack channel](https://orama.to/slack) # Highlighted features - [Vector Search](https://docs.oramasearch.com/open-source/usage/search/vector-search) -- [Search filters](https://docs.oramasearch.com/open-source/usage/search/filters) +- [Hybrid Search](https://docs.oramasearch.com/open-source/usage/search/hybrid-search) +- [Search Filters](https://docs.oramasearch.com/open-source/usage/search/filters) - [Geosearch](https://docs.oramasearch.com/open-source/usage/search/geosearch) - [Facets](https://docs.oramasearch.com/open-source/usage/search/facets) - [Fields Boosting](https://docs.oramasearch.com/open-source/usage/search/fields-boosting) -- [Typo tolerance](https://docs.oramasearch.com/open-source/usage/search/introduction#typo-tolerance) -- [Exact match](https://docs.oramasearch.com/open-source/usage/search/introduction#exact-match) +- [Typo Tolerance](https://docs.oramasearch.com/open-source/usage/search/introduction#typo-tolerance) +- [Exact Match](https://docs.oramasearch.com/open-source/usage/search/introduction#exact-match) +- [BM25](https://docs.oramasearch.com/open-source/usage/search/bm25-algorithm) - [Stemming and tokenization in 28 languages](https://docs.oramasearch.com/open-source/text-analysis/stemming) +- [Plugin System](https://docs.oramasearch.com/open-source/plugins/introduction) # Installation -You can install Orama using `npm`, `yarn`, `pnpm`: +You can install Orama using `npm`, `yarn`, `pnpm`, `bun`: ```sh npm i @orama/orama ``` -```sh -yarn add @orama/orama -``` - -```sh -pnpm add @orama/orama -``` - Or import it directly in a browser module: ```html @@ -52,6 +49,12 @@ Or import it directly in a browser module: ``` +With Deno, you can just use the same CDN URL or use npm specifiers: + +```js +import { create, search, insert } from 'npm:@orama/orama' +``` + Read the complete documentation at [https://docs.oramasearch.com](https://docs.oramasearch.com). # Usage @@ -75,10 +78,23 @@ const db = await create({ }) ``` -If you are using Node.js without ESM, please see the [usage with CommonJS](#usage-with-commonjs) section below on how to properly require Orama. +Orama currently supports 10 different data types: + +| Type | Description | example | +| ---------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| `string` | A string of characters. | `'Hello world'` | +| `number` | A numeric value, either float or integer. | `42` | +| `boolean` | A boolean value. | `true` | +| `enum` | An enum value. | `'drama'` | +| `geopoint` | A geopoint value. | `{ lat: 40.7128, lon: 74.0060 }` | +| `string[]` | An array of strings. | `['red', 'green', 'blue']` | +| `number[]` | An array of numbers. | `[42, 91, 28.5]` | +| `boolean[]` | An array of booleans. | `[true, false, false]` | +| `enum[]` | An array of enums. | `['comedy', 'action', 'romance']` | +| `vector[]` | A vector of numbers to perform vector search on. | `[0.403, 0.192, 0.830]` | -Orama will only index string properties, but will allow you to set and store -additional data if needed. + +Orama will only index properties specified in the schema but will allow you to set and store additional data if needed. Once the db instance is created, you can start adding some documents: @@ -123,7 +139,7 @@ const searchResult = await search(db, { ``` In the case above, you will be searching for all the documents containing the -word `headphones`, looking up in every schema property (AKA index): +word `"headphones"`, looking up in every `string` property specified in the schema: ```js { @@ -184,61 +200,135 @@ Result: } ``` -If you want to perform a vector search, you can use the `searchVector` function: +You can use non-string data to [filter](https://docs.oramasearch.com/open-source/usage/search/filters), [group](https://docs.oramasearch.com/open-source/usage/search/grouping), and create [facets](https://docs.oramasearch.com/open-source/usage/search/facets): ```js -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 +const searchResult = await search(db, { + term: 'immersive sound quality', + where: { + price: { + lte: 199.99 + }, + rating: { + gt: 4 + } + }, }) ``` -# Usage with CommonJS +# Performing hybrid and vector search -Orama is packaged as ES modules, suitable for Node.js, Deno, Bun and modern browsers. +Orama is a full-text and vector search engine. This allows you to adopt different kinds of search paradigms depending on your specific use case. -**In most cases, simply `import` or `@orama/orama` will suffice ✨.** +To perform vector or hybrid search, you can use the same `search` method used for full-text search. -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: +You'll just have to specify which property you want to perform vector search on, and a vector to be used to perform vector similarity: ```js -async function main() { - const { create, insert } = await import('@orama/orama') +const searchResult = await searchVector(db, { + mode: 'vector', // or 'hybrid' + vector: { + value: [...], // OpenAI embedding or similar vector to be used as an input + property: 'embedding' // Property to search through. Mandatory for vector search + } +}) +``` - const db = create(/* ... */) - insert(db, { - /* ... */ - }) -} +If you're using the [Orama Secure AI Proxy](https://oramasearch.com/blog/announcing-the-orama-secure-ai-proxy) (highly recommended), you can skip the vector configuration at search time, since the official [Orama Secure AI Proxy plugin](https://www.npmjs.com/package/@orama/plugin-secure-proxy) will take care of it automatically for you: + +```js +import { create } from '@orama/orama' +import { pluginSecureProxy } from '@orama/plugin-secure-proxy' + +const secureProxy = secureProxyPlugin({ + apiKey: '', + defaultProperty: 'embedding' // the default property to perform vector and hybrid search on +}) + +const db = await create({ + schema: { + name: 'string', + description: 'string', + price: 'number', + embedding: 'vector[1536]', + meta: { + rating: 'number', + }, + }, + plugins: [secureProxy] +}) -main().catch(console.error) +const resultsHybrid = await search(db, { + mode: 'vector', // or 'hybrid' + term: 'Videogame for little kids with a passion about ice cream', + where: { + price: { + lte: 19.99 + }, + 'meta.rating': { + gte: 4.5 + } + } +}) ``` -## Use CJS requires +# Performing Geosearch -Orama methods can be required as CommonJS modules by requiring from `@orama/orama`. +Orama supports Geosearch as a search filter. It will search through all the properties specified as `geopoint` in the schema: ```js -const { create, insert } = require("@orama/orama") +import { create, insert } from '@orama/orama' -create(/* ... */) - .then(db => insert(db, { /* ... */ }) - .catch(console.error) -``` +const db = await create({ + schema: { + name: 'string', + location: 'geopoint' + } +}) -Note that only main methods are supported so for internals and other supported exports you still have to use `await import`. +await insert(db, { name: 'Duomo di Milano', location: { lat: 45.46409, lon: 9.19192 } }) +await insert(db, { name: 'Piazza Duomo', location: { lat: 45.46416, lon: 9.18945 } }) +await insert(db, { name: 'Piazzetta Reale', location: { lat: 45.46339, lon: 9.19092 } }) -# Community Rewards +const searchResult = await search(db, { + term: 'Duomo', + where: { + location: { // The property we want to filter by + radius: { // The filter we want to apply (in that case: "radius") + coordinates: { // The central coordinate + lat: 45.4648, + lon: 9.18998 + }, + unit: 'm', // The unit of measurement. The default is "m" (meters) + value: 1000, // The radius length. In that case, 1km + inside: true // Whether we want to return the documents inside or outside the radius. The default is "true" + } + } + } +}) +``` + +Orama Geosearch APIs support distance-based search (via `radius`), or polygon-based search (via `polygon`). -![Orama Community Rewards](https://raw.githubusercontent.com/oramasearch/orama/main/misc/readme/community-rewards.png) +By default, Orama will use the [**Haversine formula**](https://en.wikipedia.org/wiki/Haversine_formula) to perform Geosearch, but high-precision search can be enabled by passing the `highPrecision` option in your `radius` or `polygon` configuration. This will tell Orama to use the [**Vicenty Formulae**](https://en.wikipedia.org/wiki/Vincenty%27s_formulae) instead, which is more precise for longer distances. -Are you using Orama in production? Have you written an article or made a YouTube video on Orama? [Contact us](mailto:info@oramasearch.com) to get some Orama swag in return! +Read more in the [official docs](https://docs.oramasearch.com/open-source/usage/search/geosearch). # Official Docs Read the complete documentation at [https://docs.oramasearch.com](https://docs.oramasearch.com). +# Official Orama Plugins + +- [Plugin Vitepress](https://docs.oramasearch.com/open-source/plugins/plugin-vitepress) +- [Plugin Docusaurus](https://docs.oramasearch.com/open-source/plugins/plugin-docusaurus) +- [Plugin Telemetry](https://docs.oramasearch.com/open-source/plugins/plugin-telemetry) +- [Plugin Astro](https://docs.oramasearch.com/open-source/plugins/plugin-astro) +- [Plugin Data Persistence](https://docs.oramasearch.com/open-source/plugins/plugin-data-persistence) +- [Plugin Nextra](https://docs.oramasearch.com/open-source/plugins/plugin-nextra) + +Write your own plugin: [https://docs.oramasearch.com/open-source/plugins/writing-your-own-plugins](https://docs.oramasearch.com/open-source/plugins/writing-your-own-plugins) + # License Orama is licensed under the [Apache 2.0](/LICENSE.md) license. diff --git a/packages/orama/package.json b/packages/orama/package.json index c5fc58f2a..e41705b22 100644 --- a/packages/orama/package.json +++ b/packages/orama/package.json @@ -1,6 +1,6 @@ { "name": "@orama/orama", - "version": "2.0.0", + "version": "2.0.1", "type": "module", "description": "Next generation full-text and vector search engine, written in TypeScript", "sideEffects": false, diff --git a/packages/plugin-astro/package.json b/packages/plugin-astro/package.json index 6cb6357a5..a870999a7 100644 --- a/packages/plugin-astro/package.json +++ b/packages/plugin-astro/package.json @@ -1,7 +1,7 @@ { "name": "@orama/plugin-astro", "description": "An Astro integration for Orama", - "version": "2.0.0", + "version": "2.0.1", "keywords": [ "astro", "astro-component", diff --git a/packages/plugin-data-persistence/package.json b/packages/plugin-data-persistence/package.json index eb378e53a..e1fd9c232 100644 --- a/packages/plugin-data-persistence/package.json +++ b/packages/plugin-data-persistence/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-data-persistence", - "version": "2.0.0", + "version": "2.0.1", "description": "Data persistence plugin for Orama", "type": "module", "sideEffects": false, diff --git a/packages/plugin-docusaurus-v3/package.json b/packages/plugin-docusaurus-v3/package.json index 9b15b2446..447ffe334 100644 --- a/packages/plugin-docusaurus-v3/package.json +++ b/packages/plugin-docusaurus-v3/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-docusaurus-v3", - "version": "2.0.0", + "version": "2.0.1", "description": "Docusaurus plugin for local search powered by orama", "keywords": [ "orama", diff --git a/packages/plugin-docusaurus/package.json b/packages/plugin-docusaurus/package.json index 5765e6ef8..0e6920c27 100644 --- a/packages/plugin-docusaurus/package.json +++ b/packages/plugin-docusaurus/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-docusaurus", - "version": "2.0.0", + "version": "2.0.1", "description": "Docusaurus plugin for local search powered by orama", "keywords": [ "orama", diff --git a/packages/plugin-match-highlight/package.json b/packages/plugin-match-highlight/package.json index 59ef81f82..397077990 100644 --- a/packages/plugin-match-highlight/package.json +++ b/packages/plugin-match-highlight/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-match-highlight", - "version": "2.0.0", + "version": "2.0.1", "description": "Orama plugin for search match highlighting", "keywords": [ "full-text search", diff --git a/packages/plugin-nextra/package.json b/packages/plugin-nextra/package.json index 3df7359b1..c66ee3d5c 100644 --- a/packages/plugin-nextra/package.json +++ b/packages/plugin-nextra/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-nextra", - "version": "2.0.0", + "version": "2.0.1", "description": "Nextra plugin for local search powered by orama", "keywords": [ "orama", diff --git a/packages/plugin-parsedoc/package.json b/packages/plugin-parsedoc/package.json index f10ac1b54..91e2e454a 100644 --- a/packages/plugin-parsedoc/package.json +++ b/packages/plugin-parsedoc/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-parsedoc", - "version": "2.0.0", + "version": "2.0.1", "description": "Orama plugin to populate an index with HTML/Markdown documents", "keywords": [], "author": "", diff --git a/packages/plugin-secure-proxy/package.json b/packages/plugin-secure-proxy/package.json index 3b25bf89f..d4365b509 100644 --- a/packages/plugin-secure-proxy/package.json +++ b/packages/plugin-secure-proxy/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-secure-proxy", - "version": "2.0.0", + "version": "2.0.1", "description": "Orama plugin for generating embeddings securely on the front-end", "keywords": [ "orama", diff --git a/packages/plugin-telemetry/package.json b/packages/plugin-telemetry/package.json index 0841971ed..96d238de8 100644 --- a/packages/plugin-telemetry/package.json +++ b/packages/plugin-telemetry/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-telemetry", - "version": "2.0.0", + "version": "2.0.1", "description": "Orama plugin for providing telemetry data on your searches", "keywords": [ "orama", diff --git a/packages/plugin-vitepress/package.json b/packages/plugin-vitepress/package.json index 59a347252..b8b4cd9ca 100644 --- a/packages/plugin-vitepress/package.json +++ b/packages/plugin-vitepress/package.json @@ -1,6 +1,6 @@ { "name": "@orama/plugin-vitepress", - "version": "2.0.0", + "version": "2.0.1", "description": "Vitepress plugin for local search powered by orama", "keywords": [ "orama", diff --git a/packages/stemmers/package.json b/packages/stemmers/package.json index b8534b2fc..a31f011f0 100644 --- a/packages/stemmers/package.json +++ b/packages/stemmers/package.json @@ -1,6 +1,6 @@ { "name": "@orama/stemmers", - "version": "2.0.0", + "version": "2.0.1", "type": "module", "description": "Stemmers for Orama", "sideEffects": false, diff --git a/packages/stopwords/package.json b/packages/stopwords/package.json index 92d143b9d..a1bc81ed1 100644 --- a/packages/stopwords/package.json +++ b/packages/stopwords/package.json @@ -1,6 +1,6 @@ { "name": "@orama/stopwords", - "version": "2.0.0", + "version": "2.0.1", "type": "module", "description": "Stop-words for Orama", "sideEffects": false,