find()
Retrieves the most relevant documents
This guide will walk you through using Memora’s find()
method. Understanding how to retrieve documents is vital, and we recommend you to start with our main search introduction for a solid foundation.
Basic usage
Here’s a simple illustration of how to use the find()
method for retrieving documents from Memora:
import Memora
memora = Memora.auth('your-api-key')
docs = (
memora
.find('the meaning of life')
.go()
)
In this example, we retrieved the top 3 most relevant documents related to the meaning of life
from the default collection.
Syntax
find(query, quantity)
Parameters
Your search query.
The desired number of documents you want Memora to return. The maximum value is 20 and the default value is 3.
Return value
The find()
method returns an array of the quantity
most relevant documents in order of relevancy — the document at index 0
is the most relevant. Each document in the array follows this structure:
{
id: '2d9b2e9e-3e0c-4d99-aa00-9b211124522a',
content: 'The Answer to the Ultimate Question of Life, the Universe, and Everything is 42',
metadata: {
from: "The Hitchhiker's Guide to the Galaxy",
type: 'book',
release_year: 1979
}
}
Searching within a collection
Documents are always stored within a collection. In the previous examples, the search was conducted in the default collection as we didn’t specify one.
Example
To specify a collection, simply use the on()
method before calling find()
:
docs = (
memora
.in('collection-name')
.find(query)
.go()
)
Syntax
on(collection)
Parameters
This is the collection name that Memora will search documents in.
Metadata filtering
Documents can have metadata and you might need to filter your search based on certain attributes or metadata of your documents. Memora makes it easy to do so.
Example
docs = (
memora
.on('book-citations')
.find('the meaning of life')
.where('published_at', '>', 1978)
.go()
)
Syntax
where(path, operator, value)
Parameters
This refers to the property in the document metadata you wish to filter.
This determines the comparison mode for the filtering. More on operators below.
The value that the metadata property is compared against.
Metadata operators
Memora supports a variety of operators for precise querying.
Name | Availability | Description |
---|---|---|
= | Always | Returns true if the value of path equals value |
!= | Always | Returns true if the value of path does not equal value |
> | The value of path and value are numbers | Returns true if the value of path is greater than value |
>= | The value of path and value are numbers | Returns true if the value of path is greater than or equal to value |
< | The value of path and value are numbers | Returns true if the value of path is less than value |
<= | The value of path and value are numbers | Returns true if the value of path is less than or equal to value |
contains | Value of path is array and value is not array | Returns true if value is found within the path array. Example here |
in | Value of path is not array and value is array | Returns true if the value of path is found within the value array. Example here |
We are continuously working on adding new operators for more intricate queries. If you need an operator not listed above, please contact us.
For the examples below, consider a collection named book-citations
containing documents in the following format:
[
{
"id": "01H3YY4RTACHHNMSM71JNREP56",
"content": "The Answer to the Ultimate Question of Life, the Universe, and Everything is 42",
"metadata": {
"book": "The Hitchhiker's Guide to the Galaxy",
"author": "Douglas Adams",
"published_at": 1978,
"genres": ["science fiction", "humor"]
}
},
// ...
]
contains
example
You want to find book citations that discuss the meaning of life, but only those of the genre science fiction
:
docs = (
memora
.on('book-citations')
.find('the meaning of life')
.where('genres', 'contains', 'science fiction')
.go()
)
in
example
You want to find book citations that discuss the meaning of life, but only those of that are from Douglas Adams
or George Orwell
:
docs = (
memora
.on('book-citations')
.find('the meaning of life')
.where('author', 'in', ['Douglas Adams', 'George Orwell'])
.go()
)
Advanced Filtering: Using And()
& Or()
You can string together multiple filtering conditions.
docs = (
memora
.find('the meaning of life')
.where('genres', 'contains', 'science fiction')
.And('author', '=', 'Douglas Adams')
)
Syntax
And(path, operator, value)
Or(path, operator, value)
Parameters
This refers to the property in the document metadata you wish to filter.
This determines the comparison mode for the filtering. To learn more about the available operators, read above.
The value that the metadata property is compared against.
Chaining multiple filters
You can chain as many And()
or Or()
modifiers as you like after a where()
filter. For example:
docs = memora
.in('book-citations')
.find('the meaning of life')
.where('published_at', '>', 1978)
.And('genre', 'contains', 'biography')
.And('author', '!=', 'Adam Smith')
.go();
Note: Currently, Memora does not support chaining an And()
with an Or()
. We’re working on this feature and aim to roll it out soon.
Wrapping up
That’s it for now about the find()
method. You should be able to retrieve documents based on sophisticated queries. In the next section, we’ll delve into the delete()
method for erasing documents and collections in Memora.
If you have further questions or need additional clarification, please don’t hesitate to reach out via our support channels.