search.md

Search

With the current version of Lyra, only type string properties are searchable, however, this does not prevent the addition of different types of properties. Lyra will keep them in memory and send the entire document back whenever there's a match for a query on searchable properties.

Search

Let's say we have a database that contains some elements:

import { create, insert, search } from '@lyrasearch/lyra'; 

const movieDB = create({
  schema: {
    title: 'string',
    director: 'string',
    plot: 'string',
    year: 'number',
    isFavorite: 'boolean'
  }
});

insert(movieDB, {
  title: 'The prestige',
  director: 'Christopher Nolan',
  plot: 'Two friends and fellow magicians become bitter enemies after a sudden tragedy. As they devote themselves to this rivalry, they make sacrifices that bring them fame but with terrible consequences.',
  year: 2006,
  isFavorite: true
});

insert(movieDB, {
  title: 'Big Fish',
  director: 'Tim Burton',
  plot: 'Will Bloom returns home to care for his dying father, who had a penchant for telling unbelievable stories. After he passes away, Will tries to find out if his tales were really true.',
  year: 2004,
  isFavorite: true
});

insert(movieDB, {
  title: 'Harry Potter and the Philosopher\'s Stone',
  director: 'Chris Columbus',
  plot: 'Harry Potter, an eleven-year-old orphan, discovers that he is a wizard and is invited to study at Hogwarts. Even as he escapes a dreary life and enters a world of magic, he finds trouble awaiting him.',
  year: 2001,
  isFavorite: false
});

{% hint style="info" %} Notice that we are also importing the search method {% endhint %}

We can now search for one (or multiple) documents as easily as:

const searchResult = search(movieDB, {
  term: "Harry",
  properties: "*",
});

Filters

The object that defines our query, in this case {term: 'Harry', properties: '*'}, can be shaped, by setting additional properties (filters), to "tighten" or "loosen" our query.

Search term

The term property specifies the word to be searched.

const searchResult = search(movieDB, {
  term: 'Chris',
});

We are now searching for all the documents that contain the word Chris.

Search properties

The properties property defines in which property to run our query.

const searchResult = search(movieDB, {
  term: 'Chris',
  properties: ['director']
});

We are now searching for all the documents that contain the word Chris in the director property.

We can also search through nested properties:

const searchResult = search(movieDB, {
  term: 'Chris',
  properties: ['cast.director'],
});

By default, Lyra searches in all searchable properties.

Exact match

The exact property finds all the document with an exact match of the term property.

const searchResult = search(movieDB, {
  term: 'Chris',
  properties: ['director'],
  exact: true,
});

We are now searching for all the documents that contain exactly the word Chris in the director property.

Without the exact property, for example, the term Christopher Nolan would be returned as well, as it contains the word Chris.

Typo tolerance

The tolerance property allows specifying the maximum distance (following the Levenshtein algorithm) between the term and the searchable property.

The Levenshtein distance is a string metric for measuring the difference between two sequences. Informally, the Levenshtein distance between two words is the minimum number of single-character edits (insertions, deletions or substitutions) required to change one word into the other.

const searchResult = search(movieDB, {
  term: 'Cris',
  properties: ['director'],
  tolerance: 1,
});

We are searching for all the documents that contain a term with an edit distance of 1 (e.g. Chris) in the director property.

{% hint style="warning" %} Tolerance doesn't work together with the exact parameter. Exact will have priority. {% endhint %}

Results limits

The limit property limits the result at the specified number.

const searchResult = search(movieDB, {
  term: 'Chris',
  properties: ['director'],
  limit: 1,
});

We are searching for the first document that contains the term Chris in the director property.

Results offset

The offset property skips the first X results.

const searchResult = search(movieDB, {
  term: 'Chris',
  properties: ['director'],
  offset: 1,
});

We are searching for all the documents that contains the term Chris in the director property, but returning the document at offset 1.

{% hint style="info" %} By default, Lyra limits the search results to 10, without any offset (so, 0 as offset value). {% endhint %}

What does the search method return?​

Now that we have learned how to perform searches on a Lyra database, we can briefly analyze the response that Lyra gives us back.

Let's say we have run the following query:

const searchResult = search(movieDB, {
  term: "Cris",
  properties: ["director"],
  tolerance: 1,
});

Whether the document was found or not, Lyra gives back an object with the following properties:

{
  elapsed: 181208n,
  count: 2,
  hits: [
    {
      id: '37149225-243',
      score: 0.23856062735983122,
      document: {
        title: "Harry Potter and the Philosopher's Stone",
        director: 'Chris Columbus',
        plot: 'Harry Potter, an eleven-year-old orphan, discovers that he is a wizard and is invited to study at Hogwarts. Even as he escapes a dreary life and enters a world of magic, he finds trouble awaiting him.',
        year: 2001,
        isFavorite: false
      }
    },
    {
      id: '37149225-5',
      score: 0.21267890323564321,
      document: {
        title: 'The prestige',
        director: 'Christopher Nolan',
        plot: 'Two friends and fellow magicians become bitter enemies after a sudden tragedy. As they devote themselves to this rivalry, they make sacrifices that bring them fame but with terrible consequences.',
        year: 2006,
        isFavorite: true
      }
    }
  ]
}

Property	Type	Description
elapsed	BigInt	Time taken to execute the query.
hits	object	Array of results containing result score (from 0 to 1 based on relevance), Lyra's ID, and original document.
count	number	Number of total results.