First of all, welcome to Orama; we know you are going to love it here!

Today, we are going to walk you through setting up your first Orama index and integrating it into a small React application.

If you want to follow along you will need two things:

• The starter code you can find at GitHub at askorama/videos-code

• The JSON file I import into Orama that you can find also on GitHub

Now that you have all the resources you need to follow along, let’s start by creating our index in the Orama Cloud.

Creating and feeding our Index

If this is your first time creating an index, you will see a page like this, which has three options.

In this example, we will use a JSON file to add data to our index, so we want to click the first one that says Import from files.

After this we will ask you for an index name, you can name it anything, this is just for you to know what each index in your account does.

In my case I called it PS1 Games since our dataset is a bunch of games for the original PlayStation.

After that lets choose JSON file as our type and click on Create Index

Our index is now created but empty and let’s change that right now by dragging our JSON file into the browser tab.

Now you can see we ask you for the Searchable properties of your index and this is a JSON Schema where you can tell Orama what properties to perform the search on.

This doesn't mean that these properties will be the ones returned, but rather that when searching for a specific term like "tekken", Orama will search within these properties thus making it much faster and our results much more accurate.

When we look at our JSON file we really only want to search in the name, slug and summary so in the input we can type:

{
	"name": "string",
	"summary": "string",
	"slug": "string"
}

And we are done! We can click on Save and Deploy!

After a couple of seconds we should get back our API endpoint and our Public API key save those as we will need these to create integrate this index in our application.

Creating our application

First things first we need to install the Orama SDK and we can do that by running:

npm i @oramacloud/client
# or
yarn add @oramacloud/client
# or
pnpm install @oramacloud/client

Once that is done let’s run npm run dev and open our project in a browser.

We have some static data showing some PlayStation games, but typing in the search input doesn’t really do anything.

To change that let’s head out to our App.jsx and outside our component let’s initialize the Orama SDK with the info we got in the dashboard:

import { OramaClient } from '@oramacloud/client' 

const client = new OramaClient({ 
  endpoint: 'https://cloud.orama.run/v1/indexes/ps1-games-ayu4s7', 
  api_key: 'n0z6JW7H25oAZOLHDoB4oTlsiOzQAfEU' 
})

Now that we have that lets test our index by searching for tekken. Under the line we just wrote we can add:

client.search({ term: "tekken" }).then(console.log);

What this code does is that it gets our index and searches on it for any games that have `tekken` on the name, slug or the summary. If we open the browser and look at our console we can see we do indeed get a response with some games:

{
  "hits": [
    {
      "id": 1035,
      "score": 24.746251821517944,
      "document": {
        "id": 1242,
        "name": "Tekken",
        ...
      }
    },
    {
      "id": 1033,
      "score": 21.582027912139893,
      "document": {
        "id": 1243,
        "name": "Tekken 2",
        ...
      }
    },
    {
      "id": 1034,
      "score": 20.07565987110138,
      "document": {
        "id": 1244,
        "name": "Tekken 3",
        ...
      }
    },
    {
      "id": 785,
      "score": 1.8667995929718018,
      "document": {
        "id": 44979,
        "name": "Point Blank 3",
        ...
      }
    }
  ],
  "elapsed": {
    "raw": 344999936,
    "formatted": "344ms"
  },
  "count": 4
}

We can see Orama returned games that had Tekken in their title and also returned Point Blank 3 as this one had the word Tekken in the summary.

In this response we also get the number of results found in the index that matched your search parameters and how much time the search took.

Awesome that worked! We can now start making the search work in our small application. Let’s start by creating a function called searchGames that searches for Tekken and sets our state with the games it returns:

const searchGames = async () => {
  const results = await client.search({
    term: "tekken"
  });
  setGames(results?.hits);
};

Let’s also run this when we type on the search input and the query changes

useEffect(() => {
  searchGames();
}, [query]);

This code will also run on start but in this case we want that in order to populate our page on load. If we now look at our page in the browser we can see a bunch of tekken but changing the query still does not search for what we typed.

To fix that let’s connect our searchGames function to our query like so:

const searchGames = async () => {
  const results = await client.search({
    term: query,
  });
  setGames(results?.hits || []);
};

And now it works! We get different games based on what we search!

Even though it works, we can make it better and there are two things I want to do before we wrap up, the first one that I think this is not returning enough games, I think it should return 10.

To do that lets edit our search to include a limit of 10:

const searchGames = async () => {
  const results = await client.search({
    term: query,
    limit: 10, // this line
  });
  setGames(results?.hits);
};

If we now check our page we get more results and in here you can return as many objects as you want but be aware that when returning many the calls will take longer making your search appear slower.

The final thing I want to do is to add some typo tolerance, let’s say you write tekkn instead of tekken you can see that nothing is returned. I would love to allow for at least one typo per word.

Orama makes this very simple by giving us the tolerance property, this property takes an integer and the number you pass it will be how many typos we will allow per word so let’s put that at 1.

const searchGames = async () => {
  const results = await client.search({
    term: query,
    limit: 10,
    tolerance: 1, // this line
  });
  setGames(results?.hits);
};

Doing the same search now will return the tekken games as we wanted thus making the user experience much better.

And that’s it! We created our first index, added some data to it and even integrated it in a small app. That’s pretty good for one article I would say.

You can find the finished code at GitHub and happy searching!