Adding feature descriptions #55
Conversation
Pensu
force-pushed
the
feature-descriptions
branch
from
5b8cfd2 to
e30f6ad
Compare
Pensu
changed the title
| @@ -149,6 +149,12 @@ let config = { | |||
| ['/0.19.0/guide/features/typo-tolerance', 'Typo Tolerance'], | |||
| ['/0.19.0/guide/features/faceting', 'Faceting'], | |||
| ['/0.19.0/guide/features/filtering', 'Filtering'], | |||
| ['/0.19.0/guide/features/federated', 'Federated Search'], | |||
There was a problem hiding this comment.
Let's have the route as /0.19.0/guide/features/federated-search
| @@ -149,6 +149,12 @@ let config = { | |||
| ['/0.19.0/guide/features/typo-tolerance', 'Typo Tolerance'], | |||
| ['/0.19.0/guide/features/faceting', 'Faceting'], | |||
| ['/0.19.0/guide/features/filtering', 'Filtering'], | |||
| ['/0.19.0/guide/features/federated', 'Federated Search'], | |||
| ['/0.19.0/guide/features/scoped-API-keys', 'Scoped API Keys'], | |||
There was a problem hiding this comment.
Let's call this Multi-tenant Indices.
There was a problem hiding this comment.
@jasonbosco Is that for route or title?
| ['/0.19.0/guide/features/federated', 'Federated Search'], | ||
| ['/0.19.0/guide/features/scoped-API-keys', 'Scoped API Keys'], | ||
| ['/0.19.0/guide/features/synonyms', 'Synonyms'], | ||
| ['/0.19.0/guide/features/curation', 'Curation and Merchandizing'], |
There was a problem hiding this comment.
Let's name the route as: curation-merchandizing
| ['/0.19.0/guide/features/scoped-API-keys', 'Scoped API Keys'], | ||
| ['/0.19.0/guide/features/synonyms', 'Synonyms'], | ||
| ['/0.19.0/guide/features/curation', 'Curation and Merchandizing'], | ||
| ['/0.19.0/guide/features/raft', 'Raft Based Clustering'], |
There was a problem hiding this comment.
Let's call this clustering instead of Raft.
| ['/0.19.0/guide/features/synonyms', 'Synonyms'], | ||
| ['/0.19.0/guide/features/curation', 'Curation and Merchandizing'], | ||
| ['/0.19.0/guide/features/raft', 'Raft Based Clustering'], | ||
| ['/0.19.0/guide/features/upgrade', 'Seamless Version Upgrades'], |
There was a problem hiding this comment.
Let's remove upgrades from the features section.
| @@ -149,6 +149,12 @@ let config = { | |||
| ['/0.19.0/guide/features/typo-tolerance', 'Typo Tolerance'], | |||
There was a problem hiding this comment.
What I run this on dev, I see this error:
No matching page found for sidebar item "/0.19.0/guide/features/curation"
I don't see a file called curation.md in the repo
There was a problem hiding this comment.
I haven't added it yet. Will be added in future PR. Do you want me to add a placeholder file?
There was a problem hiding this comment.
Ah I see, in that case let's remove the line from the side-bar configuration, so the nav renders in the meantime.
| @@ -0,0 +1,182 @@ | |||
| # Federated Search | |||
|
|
|||
| Federated or multi search is a way to search for documents in multiple collections as part of a single search query. Federated search can help reduce network latencies. It can also be used to present similar content from other collections, that might encourage users to browse more content across your application. For example, your application might have different collections for `Nike` and `Adidas`. Now, if a user is looking for a shoe from a specific branch and they might not know what other brands are available, the search query can perform a search on both the collections and return relevant results from both the collections. | |||
There was a problem hiding this comment.
Federated or multi search is a way to search for documents in multiple collections as part of a single search query.
[Add] ... You can also use multi-search to send multiple search queries to the same collections, essentially giving you a way to batch search queries in a single HTTP request.
There was a problem hiding this comment.
To be able to get a screenshot, could we use the example of searching for say "Canon" on this site: https://www.bhphotovideo.com/
It should show results across products, help articles and search suggestions.
| @@ -0,0 +1,47 @@ | |||
| # Scoped API Keys | |||
|
|
|||
| API keys are at the core of Typesense. To perform any action with Typesense, you need API keys. Typesense also allows access control on API keys. You can define capabilities as to what a user can or cannot do. You can also restrict access to a specific document or collection. In the case of a multi-tenant environment, you can scope API keys to a particular subset. This is helpful when you have indexed data from multiple tenants in your Typesense server and want to restrict users to only access their subset of data. | |||
There was a problem hiding this comment.
Instead of :
API keys are at the core of Typesense.
Typesense is designed with security and fine-grained access control in mind.
|
|
||
| Typesense allows you to create API keys that have pre-defined filters embedded in them. So, whenever you run a search query with these API keys, those filters are automatically applied and cannot be overridden. You can then provide those search API keys to users and they would only be able to access the data that is allowed by the set filter. To create scoped API keys, you just need a parent key. | ||
|
|
||
| Let's create a scoped search API key that will restrict users to only access documents that have the company id 124: |
There was a problem hiding this comment.
Could you add a sample set of documents, showing company_id set to different values. And how a user using a scoped key with company_id: 124 only gets records with that company_id and not others?
| @@ -0,0 +1,3 @@ | |||
| # Upgrades | |||
There was a problem hiding this comment.
We can remove this section from the features section.
| @@ -0,0 +1,5 @@ | |||
| # Raft Based Clustering | |||
|
|
|||
| High availability is essential for production environments. Typesense uses [Raft algorithm](https://raft.github.io/) to create a highly available cluster with more than one Typesense servers. Based on raft consensus, to handle 1-node failure, you need to create a cluster with 3 nodes. Similarly for 2-node failure, you need to create a 5 node cluster. Note that adding more nodes will also add write latencies. | |||
There was a problem hiding this comment.
uses Raft algorithm
Correction: "uses the Raft Consensus Algorithm"
Based on raft consensus, to handle 1-node failure, you need to create a cluster with 3 nodes. Similarly for 2-node failure, you need to create a 5 node cluster.
Correction:
With Raft, you need to create a cluster of 3 nodes to tolerate single node failures. If you wish to handle 2-node failures, then you need a minimum of 5 nodes in the cluster.
Note that adding more nodes will also add write latencies.
Correction:
Note that adding more nodes will also increase write latencies.
| @@ -0,0 +1,94 @@ | |||
| # Sorting | |||
|
|
|||
| Sorting is the ordering of search results either in ascending or descending order based on a specific parameter. | |||
There was a problem hiding this comment.
based on a specific parameter.
"based on one or more parameters"
Pensu
force-pushed
the
feature-descriptions
branch
2 times, most recently
from
c442c1c to
9453ff6
Compare
Pensu
force-pushed
the
feature-descriptions
branch
3 times, most recently
from
d00b4c9 to
354503f
Compare
Pensu
force-pushed
the
feature-descriptions
branch
from
354503f to
adb5819
Compare
| @@ -0,0 +1,170 @@ | |||
| # Scoped API Keys | |||
|
|
|||
| Typesense is designed with security and fine-grained access control in mind. To perform any action with Typesense, you need API keys. Typesense also allows access control on API keys. You can define capabilities as to what a user can or cannot do. You can also restrict access to a specific document or collection. In the case of a multi-tenant environment, you can scope API keys to a particular subset. This is helpful when you have indexed data from multiple tenants in your Typesense server and want to restrict users to only access their subset of data. | |||
There was a problem hiding this comment.
In the case of a multi-tenant environment, you can scope API keys to a particular subset
... to a particular subset of records.
This is helpful when you have indexed data from multiple tenants
tenants -> users
|
|
||
| Typesense is designed with security and fine-grained access control in mind. To perform any action with Typesense, you need API keys. Typesense also allows access control on API keys. You can define capabilities as to what a user can or cannot do. You can also restrict access to a specific document or collection. In the case of a multi-tenant environment, you can scope API keys to a particular subset. This is helpful when you have indexed data from multiple tenants in your Typesense server and want to restrict users to only access their subset of data. | ||
|
|
||
| Typesense allows you to create API keys that have pre-defined filters embedded in them. So, whenever you run a search query with these API keys, those filters are automatically applied and cannot be overridden. You can then provide those search API keys to users and they would only be able to access the data that is allowed by the set filter. To create scoped API keys, you just need a parent key. |
There was a problem hiding this comment.
To create scoped API keys, you just need a parent key
... a parent key that only has documents:search permissions on it.
| {"company_id":127,"company_name":"New Stark Industries","country":"USA","id":"3","num_employees":7945} | ||
| ``` | ||
|
|
||
| Now, let's create a scoped API key that will restrict access to documents that have the `company_id` value as 124. |
There was a problem hiding this comment.
Before this, could you also add a code snippet to indicate how to create a parent key with just search permissions, so this article is self-contained?
| "RDhxa2VKTnBQVkxaVlFIOS9JWDZ2bDdtMU5HL3laa0pab2pTeEUzbFBhZz1STjIzeyJmaWx0ZXJfYnkiOiJjb21wYW55X2lkOjEyNCIsImV4cGlyZXNfYXQiOjE2MTE1OTA0NjV9" | ||
| ``` | ||
|
|
||
| The `expires_at` parameter sets the expiration date for the API key and must be less that the expiration of parent API key. Let's perform a search using the scoped API key: |
There was a problem hiding this comment.
New paragraph for "Let's perform a search using the scoped API key"
| } | ||
| ``` | ||
|
|
||
| As you see in the response, the document with `company_id` set to 124 is shown in the output. There is another document that has the `company_name` as "New Stark Industries", but it won't be shown in the result. |
There was a problem hiding this comment.
but it won't be shown in the result
... because it does not match the filter ... we embedded in the scoped API key.
|
|
||
| </template> | ||
| </Tabs> | ||
|
|
There was a problem hiding this comment.
Now searching for any of blazer, coat or jacker, will return results that contain the other two terms as well, since they're defined as multi-way synonyms.
| @@ -0,0 +1,186 @@ | |||
| # Federated Search | |||
|
|
|||
| Federated or multi search is a way to search for documents in multiple collections as part of a single search query. You can also use multi-search to send multiple search queries to the same collections, essentially giving you a way to batch search queries in a single HTTP request. Federated search can help reduce network latencies. It can also be used to present similar content from other collections, that might encourage users to browse more content across your application. For example, your application might have different collections for `Nike` and `Adidas`. Now, if a user is looking for a shoe from a specific branch and they might not know what other brands are available, the search query can perform a search on both the collections and return relevant results from both the collections. | |||
There was a problem hiding this comment.
to present similar content from other collections
to present results for the same search query from multiple collections...
There was a problem hiding this comment.
For example, your application might have different collections for Nike and Adidas. Now, if a user is looking for a shoe from a specific branch and they might not know what other brands are available, the search query can perform a search on both the collections and return relevant results from both the collections.
This example is a little confusing. Now that we have the BHP example below, let's remove this one.
| @@ -0,0 +1,186 @@ | |||
| # Federated Search | |||
There was a problem hiding this comment.
Let's call this file federated-search.md so the url has the word search
|
|
||
| Federated or multi search is a way to search for documents in multiple collections as part of a single search query. You can also use multi-search to send multiple search queries to the same collections, essentially giving you a way to batch search queries in a single HTTP request. Federated search can help reduce network latencies. It can also be used to present similar content from other collections, that might encourage users to browse more content across your application. For example, your application might have different collections for `Nike` and `Adidas`. Now, if a user is looking for a shoe from a specific branch and they might not know what other brands are available, the search query can perform a search on both the collections and return relevant results from both the collections. | ||
|
|
||
| For example, if you search for `Canon` on https://www.bhphotovideo.com/, you would see that there are multiple results shown including products, suggestions and help resources: |
There was a problem hiding this comment.
products, suggestions and help resources...
each of which could be indexed in separate collections, but the search term Canon is sent to all three indices and results From multiple collections are shown side-by-side
|
|
||
|  | ||
|
|
||
| Typesense supports searching across multiple collections in a single HTTP request. Let's create a search query for shoes: |
There was a problem hiding this comment.
Could use make an example though would mimic the BHP example from above, searching across 3 collections?
Change Summary
This PR adds feature descriptions for federated search, high availability, scoped API keys, sorting, synonyms and upgrades.
PR Checklist