Search Documents
Tigris offers a realtime search for documents in a collection. The fields need to be annotated in order to be indexed. Please check data modeling section. This guide section will walk through how to use Tigris search in different scenarios.
Example collection
Let's first have the collection.
catalogs := tigris.GetCollection[Catalog](catalogdb)
Assuming an e-commerce website that has the above collection catalog and has 6 products(documents) in it.
id | name | price | brand | labels | popularity | reviews |
---|---|---|---|---|---|---|
1 | fiona handbag | 99.9 | michael kors | purses | 8 | {"author": "alice", "rating": 7} |
2 | tote bag | 49 | coach | handbags | 9 | {"author": "olivia", "rating": 8.3} |
3 | sling bag | 75 | coach | purses | 9 | {"author": "alice", "rating": 9.2} |
4 | sneakers shoes | 40 | adidas | shoes | 10 | {"author": "olivia", "rating": 9} |
5 | running shoes | 89 | nike | shoes | 10 | {"author": "olivia", "rating": 8.5} |
6 | running shorts | 35 | adidas | clothing | 7 | {"author": "olivia", "rating": 7.5} |
Searching for documents
Search consists of executing a query against one or more text fields. Let's perform a simple search query to lookup any items matching "running".
request := search.NewRequestBuilder().WithQuery("running").Build()
it, err := catalogs.Search(ctx, request)
if err != nil {
// handle error
}
defer it.Close()
var result search.Result[Catalog]
for it.Next(&result) {
fmt.Printf("%+v\n", result)
}
if it.Err() != nil {
// handle streaming error
}
Search is case insensitive i.e. a search for term "ruNninG"
would match all of ["Running", "running", "RUnnIng", "RUNNING"]
etc.
Phrase search
By default, search is performed over individual terms in the text. For example, search for a
query string adventure park
in a dataset would yield following results:
- "California's kids adventure park and Safari"
- "Adventure island and water park"
- "Long Island water park and adventure activities"
- "Six flags kids recreation and adventure park"
- "Hollywood adventure park and studios"
- "Seaworld adventure and theme park"
The search phrase can be escaped in query for exact match. In the above example, querying for exact
phrase \"adventure park\"
would return:
- "California's kids adventure park and Safari"
- "Six flags kids recreation and adventure park"
- "The Great America adventure park and Zoo"
Phrases can still be combined with keywords for richer text search. Continuing above example,
the query string kids \"adventure park\"
would result in:
- "California's kids adventure park and Safari"
- "Six flags kids recreation and adventure park"
phraseSearch := search.NewRequestBuilder().WithQuery("\"adventure park\"").Build()
mixedSearch := search.NewRequestBuilder().WithQuery("kids \"adventure park\"").Build()
Match all search query
When query string isn't specified or an empty string (""
), a match all query is performed.
It returns all searchable documents, modified by any filters or search parameters used.
request := search.MatchAll().Build()
Returning all documents is typically useful when used in conjunction with filter, or when performing a faceted search across the collection.
Project search query against specific fields
We can optionally project the search query against selected fields. Continuing previous example of
searching for "running", we may not want to search in reviews
field and avoid any
unwanted results.
request := search.NewRequestBuilder().
WithQuery("running").
WithSearchFields("Name", "Labels").
Build()
Refine the search results using filters
Applying filter on search results
Filters can be used to match against one or more field values in a collection. For example, to
fetch all items from brand
"adidas".
request := search.MatchAll().
WithFilter(filter.Eq("Brand", "adidas")).
Build()
Applying complex filter on search results
Let's adjust the query to only return items in price
range of [40, 90). We can use
filters in search to further refine the results.
request := search.NewRequestBuilder().
WithQuery("running").
WithSearchFields("Name", "Labels").
WithFilter(
filter.And(filter.Gte("Price", 40), filter.Lt("Price", 90))).
Build()
Supported filter operators
The following filter operators are supported:
$eq
- Matches documents where the field value is equal to the provided value.$lt
- Matches documents where the field value is less than the provided value.$lte
- Matches documents where the field value is less than or equal to the provided value.$gt
- Matches documents where the field value is greater than the provided value.$gte
- Matches documents where the field value is greater than or equal to the provided value.$not
- Matches documents where the field value is not equal to the provided value.$contains
- Matches documents where the the provided value is a substring of the field value.$regexp
- Matches documents where the field value matches the given regex.$and
- Matches documents where all of the provided filters match.$or
- Matches documents where at least one of the provided filters match.
Faceted search
We can additionally retrieve the number of items a particular brand
has and unique labels
,
that match our search query.
request := search.NewRequestBuilder().
WithQuery("running").
WithSearchFields("Name", "Labels").
WithFilter(
filter.And(filter.Gte("Price", 40), filter.Lt("Price", 90))).
WithFacetFields("Brand", "Labels").
Build()
Facets are a specific use-case of filters, and can only be used for filterable attributes.
Common application for faceted search is to build UX with quick filters, that users can use to narrow search results in real-time. Faceted search interface presents intuitive content navigation to the end user.
Sorting the search results
Tigris lets you specify an order to sort the search results. We can specify a ranking order in our search query to have results sorted with more popular items appearing first.
request := search.NewRequestBuilder().
WithQuery("running").
WithSearchFields("Name", "Labels").
WithSorting(sort.Descending("Popularity"))
Build()
Many documents may have the same popularity
score, we can specify additional user-defined sortable
field to break the tie.
request := search.NewRequestBuilder().
WithQuery("running").
WithSearchFields("Name", "Labels").
WithSorting(sort.Descending("Popularity"), sort.Descending("Reviews.Rating"))
Build()
The results will be first sorted by value of popularity
field, reviews.rating
will be used to
decide ordering if two matching documents have same popularity
.
Documents can only be sorted by integer
, number
and date-time
type of collection fields.
Specifying document fields to retrieve
Search query can be programmed to return only specific fields in a document in search results. We
may only need to retrieve product name
, brand
and price
for our interface.
request := search.NewRequestBuilder().
WithQuery("running").
WithIncludeFields("Name", "Brand", "Price").
Build()
On the contrary, exclusion of fields is useful to exclude/hide potentially sensitive fields or
internal metadata from the document. To include all fields except id
and reviews
from documents
in search results.
request := search.NewRequestBuilder().
WithQuery("running").
WithExcludeFields("Id", "Reviews").
Build()
Field selection does not impact searching, filtering and faceting capabilities for that field. For
example, if reviews
field is not included in documents in search results, it could still be used
for text querying, filtering and/or faceting; just that matched documents won't include reviews
field.
Case Insensitive Search Result Filtering
Search is case-insensitive but the filtering to restrict the search result is case-sensitive by default. Tigris supports
Collation which allows you to specify string comparison rules for filtering on text fields. Set the case to ci
in the
collation object to make it case-insensitive. The following example is showing when you are searching for text "running"
and you need to filter by brand
field, but you don't care about the case.
request := search.NewRequestBuilder().
WithQuery("running").
WithFilter(filter.Eq("Brand", "Adidas")).
WithOptions(&search.Options{
Collation: &driver.Collation{
Case: "ci",
},
}).
Build()
Paginating through search results
Using page numbers
To retrieve a page of results, you can simply use Search
method with page number and
page size. Following query fetches the first page of results with page size set as 10
it, err := catalog.Search(ctx, &search.Request{
Q: "*",
Options: &search.Options{PageSize: 5, Page: 1},
})
if err != nil {
panic(err)
}
var res search.Result[model.Catalog]
for it.Next(&res) {
for _, v := range res.Hits {
fmt.Printf("%+v\n", v.Document)
}
}
if it.Err() != nil {
panic(it.Err())
}
Details
Output
&{Brand:AllSaints Id:72b8f1f4-9e91-43d9-8b8f-c26d7413990f Labels: Name:leather jacket Popularity:0 Price:200 Review:{Author:jane Rating:9.7}}
&{Brand:Puma Id:5af290ce-8c22-4460-9e33-9a9a869df8b9 Labels: Name:sneakers Popularity:0 Price:80 Review:{Author:joe Rating:8.5}}
&{Brand:Kate Spade Id:34e601bf-0c7b-4bea-8ab4-e4c4c7f44d54 Labels: Name:satchel bag Popularity:0 Price:120 Review:{Author:mary Rating:9.8}}
&{Brand:Levi's Id:2a2d47f2-099a-4391-90f8-d52c8a06a9a9 Labels: Name:denim jeans Popularity:0 Price:55 Review:{Author:joe Rating:7.5}}
&{Brand:Clarks Id:1df0a235-ecda-416f-b19a-7e89c1dcd2c8 Labels: Name:leather shoes Popularity:0 Price:110 Review:{Author:jane Rating:9.5}}
The hitsPerPage
parameter controls the number of documents to include in a result page. The returned
array of documents is accessible under hits
key along with some search metadata.
var res search.Result[model.Catalog]
for it.Next(&res) {
for _, v := range res.Hits {
fmt.Printf("%+v\n", v.Document)
}
}
Details
Output
&{Brand:adidas Id:a3e3c779-31cb-4d60-87cb-c4edc64ab4b7 Labels:clothing Name:running shorts Popularity:7 Price:35 Review:{Author:olivia Rating:0}}
&{Brand:nike Id:1aeb7c50-201d-42e8-8b77-23f3a3b86a89 Labels:shoes Name:running shoes Popularity:10 Price:89 Review:{Author:olivia Rating:0}}
Additionally, search result contains metadata object having current page and total pages along with other information.
var res search.Result[model.Catalog]
for it.Next(&res) {
fmt.Printf("%+v\n", res.Meta)
}
Details
Output
{Found:12 TotalPages:3 Page:{Current:1 Size:5}}
Infinite scrolling
Infinite scrolling also loads data in pages, it is just that the UX is more fluid.
Instead of using page number, an Iterator object can be obtained from search
method call and processed iteratively.
it, err := catalog.Search(ctx, &search.Request{
Q: "*",
Options: &search.Options{PageSize: 5},
})
if err != nil {
panic(err)
}
var res search.Result[model.Catalog]
for it.Next(&res) {
for _, v := range res.Hits {
fmt.Printf("%+v\n", v.Document)
}
fmt.Printf("%+v\n\n", res.Meta)
}
if it.Err() != nil {
panic(it.Err())
}
Details
Output
&{Brand:AllSaints Id:72b8f1f4-9e91-43d9-8b8f-c26d7413990f Labels: Name:leather jacket Popularity:0 Price:200 Review:{Author:jane Rating:9.7}}
&{Brand:Puma Id:5af290ce-8c22-4460-9e33-9a9a869df8b9 Labels: Name:sneakers Popularity:0 Price:80 Review:{Author:joe Rating:8.5}}
&{Brand:Kate Spade Id:34e601bf-0c7b-4bea-8ab4-e4c4c7f44d54 Labels: Name:satchel bag Popularity:0 Price:120 Review:{Author:mary Rating:9.8}}
&{Brand:Levi's Id:2a2d47f2-099a-4391-90f8-d52c8a06a9a9 Labels: Name:denim jeans Popularity:0 Price:55 Review:{Author:joe Rating:7.5}}
&{Brand:Clarks Id:1df0a235-ecda-416f-b19a-7e89c1dcd2c8 Labels: Name:leather shoes Popularity:0 Price:110 Review:{Author:jane Rating:9.5}}
{Found:12 TotalPages:3 Page:{Current:1 Size:5}}
&{Brand:Fossil Id:01a83c14-3d67-438c-b3cf-2b75a09c34d6 Labels: Name:leather wallet Popularity:0 Price:65 Review:{Author:john Rating:8.5}}
&{Brand:adidas Id:a3e3c779-31cb-4d60-87cb-c4edc64ab4b7 Labels: Name:running shorts Popularity:0 Price:35 Review:{Author:olivia Rating:7.5}}
&{Brand:nike Id:1aeb7c50-201d-42e8-8b77-23f3a3b86a89 Labels: Name:running shoes Popularity:0 Price:89 Review:{Author:olivia Rating:8.5}}
&{Brand:adidas Id:24034d4c-4de4-4ee7-8492-0d0f27b8d46b Labels: Name:sneakers shoes Popularity:0 Price:40 Review:{Author:olivia Rating:9}}
&{Brand:coach Id:4b4f7e06-025a-4b70-853f-0be7a38d221d Labels: Name:sling bag Popularity:0 Price:75 Review:{Author:alice Rating:9.2}}
{Found:12 TotalPages:3 Page:{Current:2 Size:5}}
&{Brand:coach Id:c7ec6a25-6a7a-4d9b-bced-6b40f6d097c6 Labels: Name:tote bag Popularity:0 Price:49 Review:{Author:olivia Rating:8.3}}
&{Brand:michael kors Id:2f7301f2-69b2-4b67-a3e3-9d9e7cda5948 Labels: Name:fiona handbag Popularity:0 Price:99.9 Review:{Author:alice Rating:7}}
{Found:12 TotalPages:3 Page:{Current:3 Size:5}}
As you can see, the iterator returns the same SearchResult
object as in previous section
with pagination metadata.