diff --git a/.vuepress/config.js b/.vuepress/config.js index dc06a95501..a1f4585cb5 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -11,128 +11,145 @@ module.exports = { sidebarDepth: 1, smoothScroll: true, nav: [ - { text: 'Guides', link: '/guides/' }, - { text: 'API References', link: '/references/' }, - { text: 'Resources', link: '/resources/' }, - { text: 'FAQ', link: '/faq/' }, + { text: 'Learn', link: '/learn/' }, + { text: 'Create', link: '/create/' }, + { text: 'Reference', link: '/reference/' }, { text: 'Slack', link: 'https://slack.meilisearch.com' }, ], sidebar: { - '/guides/': [ + '/learn/': [ { - title: '🚀 Introduction', - path: '/guides/introduction/', + title: '🔎 What Is MeiliSearch?', + path: '/learn/what_is_meilisearch/', collapsable: false, children: [ - '/guides/introduction/quick_start_guide', - '/guides/introduction/whats_next', + '/learn/what_is_meilisearch/features', + '/learn/what_is_meilisearch/philosophy', + '/learn/what_is_meilisearch/sdks', + '/learn/what_is_meilisearch/comparison_to_alternatives', + '/learn/what_is_meilisearch/contact', ], }, { - title: '💡 Main concepts', - path: '/guides/main_concepts/', + title: '🚀 Tutorials', + path: '/learn/tutorials/', collapsable: false, children: [ - '/guides/main_concepts/indexes', - '/guides/main_concepts/documents', - '/guides/main_concepts/search', - '/guides/main_concepts/relevancy', + '/learn/tutorials/getting_started', + '/learn/tutorials/whats_next', ], }, { - title: '📚 Advanced Guides', - path: '/guides/advanced_guides/', + title: '💡 Core Concepts', + path: '/learn/core_concepts/', collapsable: false, children: [ - '/guides/advanced_guides/installation', - '/guides/advanced_guides/configuration', - '/guides/advanced_guides/search_parameters', - '/guides/advanced_guides/filtering', - '/guides/advanced_guides/faceted_search', - '/guides/advanced_guides/authentication', - '/guides/advanced_guides/asynchronous_updates', - '/guides/advanced_guides/web_interface', - '/guides/advanced_guides/datatypes', - '/guides/advanced_guides/settings', - '/guides/advanced_guides/synonyms', - '/guides/advanced_guides/stop_words', - '/guides/advanced_guides/distinct', - '/guides/advanced_guides/snapshots_and_dumps', - '/guides/advanced_guides/field_properties', - '/guides/advanced_guides/typotolerance', - '/guides/advanced_guides/prefix', - '/guides/advanced_guides/concat', - '/guides/advanced_guides/bucket_sort', - '/guides/advanced_guides/known_limitations', - '/guides/advanced_guides/tokenization', + '/learn/core_concepts/documents', + '/learn/core_concepts/indexes', + '/learn/core_concepts/relevancy', + ], + }, + { + title: '📚 Advanced Topics', + path: '/learn/advanced/', + collapsable: false, + children: [ + '/learn/advanced/language', + '/learn/advanced/asynchronous_updates', + '/learn/advanced/snapshots_vs_dumps', ], }, ], - '/references/': [ + '/reference/': [ + { + title: '⭐ Feature References', + path: '/reference/features/', + collapsable: true, + children: [ + '/reference/features/authentication', + '/reference/features/configuration', + '/reference/features/distinct', + '/reference/features/dumps', + '/reference/features/faceted_search', + '/reference/features/field_properties', + '/reference/features/filtering', + '/reference/features/installation', + '/reference/features/known_limitations', + '/reference/features/search_parameters', + '/reference/features/settings', + '/reference/features/snapshots', + '/reference/features/stop_words', + '/reference/features/synonyms', + '/reference/features/web_interface', + ], + }, { title: '📒 API References', - path: '/references/', - collapsable: false, + path: '/reference/api/', + collapsable: true, children: [ - '/references/indexes', - '/references/documents', - '/references/search', - '/references/updates', - '/references/keys', + '/reference/api/indexes', + '/reference/api/documents', + '/reference/api/search', + '/reference/api/updates', + '/reference/api/keys', { title: 'Settings', - path: '/references/settings/', + path: '/reference/api/settings/', collapsable: false, children: [ { title: 'All Settings', - path: '/references/settings', + path: '/reference/api/settings', }, - '/references/synonyms', - '/references/stop_words', - '/references/ranking_rules', - '/references/attributes_for_faceting', - '/references/distinct_attribute', - '/references/searchable_attributes', - '/references/displayed_attributes', + '/reference/api/synonyms', + '/reference/api/stop_words', + '/reference/api/ranking_rules', + '/reference/api/attributes_for_faceting', + '/reference/api/distinct_attribute', + '/reference/api/searchable_attributes', + '/reference/api/displayed_attributes', ], }, - '/references/stats', - '/references/health', - '/references/version', - '/references/dump', + '/reference/api/stats', + '/reference/api/health', + '/reference/api/version', + '/reference/api/dump', ], }, - ], - '/resources/': [ { - title: '📦 Resources', - path: '/resources/', - collapsable: false, + title: '🛠️ Under the Hood', + path: '/reference/under_the_hood/', + collapsable: true, children: [ - '/resources/about_storage', - '/resources/sdks', - '/resources/comparison_to_alternatives', - '/resources/postman_collection', - '/resources/contact', + '/reference/under_the_hood/bucket_sort', + '/reference/under_the_hood/concat', + '/reference/under_the_hood/datatypes', + '/reference/under_the_hood/prefix', + '/reference/under_the_hood/storage', + '/reference/under_the_hood/tokenization', + '/reference/under_the_hood/typotolerance', ], }, + ], + '/create/': [ { - title: '🏆 Tutorials', - path: '/resources/tutorials/', + title: '📜 How To', + path: '/create/how_to/', collapsable: false, - children: ['/resources/tutorials/running_production'], + children: [ + '/create/how_to/running_production', + '/create/how_to/search_bar_for_docs', + '/create/how_to/digitalocean_droplet', + '/create/how_to/http2_ssl', + '/create/how_to/postman_collection', + '/create/how_to/meilisearch_react', + ], }, { - title: "🧷 How to's", - path: '/resources/howtos/', + title: '❓ FAQ', + path: '/create/faq', collapsable: false, - children: [ - '/resources/howtos/meilisearch_react', - '/resources/howtos/digitalocean_droplet', - '/resources/howtos/search_bar_for_docs', - '/resources/howtos/http2_ssl', - ], }, ], }, diff --git a/create/README.md b/create/README.md new file mode 100644 index 0000000000..7b30765d75 --- /dev/null +++ b/create/README.md @@ -0,0 +1,16 @@ +# Create with MeiliSearch + +Want to create a brilliant website, app, or other project with MeiliSearch? You've come to the right place. + +This section covers everything you need to bring your project from idea to completion. + +## Table of Contents + +- [📜 How To](/create/how_to): Step-by-step guides for efficient problem-solving + - [Run MeiliSearch in Production](/create/how_to/running_production.md) + - [Integrate a Relevant Search Bar to Your Documentation](/create/how_to/search_bar_for_docs.md) + - [Deploy MeiliSearch on DigitalOcean](/create/how_to/digitalocean_droplet.md) + - [Use HTTP/2 and SSL with MeiliSearch](/create/how_to/http2_ssl.md) + - [Use Postman with MeiliSearch](/create/how_to/postman_collection.md) + - [Implement Instant Search in Your React App in 5 Minutes](/create/how_to/meilisearch_react.md) +- [❓ FAQ](/create/faq.md): Frequently Asked Questions diff --git a/faq/README.md b/create/faq.md similarity index 67% rename from faq/README.md rename to create/faq.md index 4eaa8fdc16..3ce8f75dd2 100644 --- a/faq/README.md +++ b/create/faq.md @@ -9,20 +9,20 @@ If you have any questions we want to hear from you. Your feedback will help us i ## Table of contents -- [I have never used a search engine before. Can I use MeiliSearch anyway?](/faq/README.md#i-have-never-used-a-search-engine-before-can-i-use-meilisearch-anyway) -- [Do I need to configure MeiliSearch to get it working?](/faq/README.md#do-i-need-to-configure-meilisearch-to-get-it-working) -- [How to know if MeiliSearch perfectly fits my use cases?](/faq/README.md#how-to-know-if-meilisearch-perfectly-fits-my-use-cases) -- [Which languages can MeiliSearch handle?](/faq/README.md#which-languages-can-meilisearch-handle) -- [Do you provide a real dataset to test MeiliSearch?](/faq/README.md#do-you-provide-a-real-dataset-to-test-meilisearch) -- [I did a call to an API route, and I only got an `updateId` as a response. What does it mean?](/faq/README.md#i-did-a-call-to-an-api-route-and-i-only-got-an-updateid-as-a-response-what-does-it-mean) -- [I am trying to add my documents but I keep receiving a `400 - Invalid data` response.](/faq/README.md#i-am-trying-to-add-my-documents-but-i-keep-receiving-a-400-invalid-data-response) -- [My document upload failed with the `document id is missing` error.](/faq/README.md#my-document-upload-failed-with-the-document-id-is-missing-error) -- [I have uploaded my documents, but I get no result when I search in my index.](/faq/README.md#i-have-uploaded-my-documents-but-i-get-no-result-when-i-search-in-my-index) -- [Is killing a MeiliSearch process safe?](/faq/README.md#is-killing-a-meilisearch-process-safe) -- [Does MeiliSearch deliver an interface to search in my documents?](/faq/README.md#does-meilisearch-deliver-an-interface-to-search-in-my-documents) -- [I do not understand the relevancy of my search results.](/faq/README.md#i-do-not-understand-the-relevancy-of-my-search-results) -- [Do you provide a public roadmap for MeiliSearch and its integration tools?](/faq/README.md#do-you-provide-a-public-roadmap-for-meilisearch-and-its-integration-tools) -- [How can I contact the MeiliSearch team?](/faq/README.md#how-can-i-contact-the-meilisearch-team) +- [I have never used a search engine before. Can I use MeiliSearch anyway?](/create/faq.md#i-have-never-used-a-search-engine-before-can-i-use-meilisearch-anyway) +- [Do I need to configure MeiliSearch to get it working?](/create/faq.md#do-i-need-to-configure-meilisearch-to-get-it-working) +- [How to know if MeiliSearch perfectly fits my use cases?](/create/faq.md#how-to-know-if-meilisearch-perfectly-fits-my-use-cases) +- [Which languages can MeiliSearch handle?](/create/faq.md#which-languages-can-meilisearch-handle) +- [Do you provide a real dataset to test MeiliSearch?](/create/faq.md#do-you-provide-a-real-dataset-to-test-meilisearch) +- [I did a call to an API route, and I only got an `updateId` as a response. What does it mean?](/create/faq.md#i-did-a-call-to-an-api-route-and-i-only-got-an-updateid-as-a-response-what-does-it-mean) +- [I am trying to add my documents but I keep receiving a `400 - Invalid data` response.](/create/faq.md#i-am-trying-to-add-my-documents-but-i-keep-receiving-a-400-invalid-data-response) +- [My document upload failed with the `document id is missing` error.](/create/faq.md#my-document-upload-failed-with-the-document-id-is-missing-error) +- [I have uploaded my documents, but I get no result when I search in my index.](/create/faq.md#i-have-uploaded-my-documents-but-i-get-no-result-when-i-search-in-my-index) +- [Is killing a MeiliSearch process safe?](/create/faq.md#is-killing-a-meilisearch-process-safe) +- [Does MeiliSearch deliver an interface to search in my documents?](/create/faq.md#does-meilisearch-deliver-an-interface-to-search-in-my-documents) +- [I do not understand the relevancy of my search results.](/create/faq.md#i-do-not-understand-the-relevancy-of-my-search-results) +- [Do you provide a public roadmap for MeiliSearch and its integration tools?](/create/faq.md#do-you-provide-a-public-roadmap-for-meilisearch-and-its-integration-tools) +- [How can I contact the MeiliSearch team?](/create/faq.md#how-can-i-contact-the-meilisearch-team) ## I have never used a search engine before. Can I use MeiliSearch anyway? @@ -30,11 +30,11 @@ Of course! No knowledge of ElasticSearch or Solr is required to use MeiliSearch. MeiliSearch is really **easy to use** and thus accessible to all kinds of developers. -[Take a quick tour](/guides/introduction/quick_start_guide.md) to learn the basics of MeiliSearch! +[Take a quick tour](/learn/tutorials/getting_started.md) to learn the basics of MeiliSearch! -We also provide a lot of tools, including [SDKs](/resources/sdks.md), to help you integrate easily MeiliSearch in your project. We're adding new tools every day! +We also provide a lot of tools, including [SDKs](/learn/what_is_meilisearch/sdks.md), to help you integrate easily MeiliSearch in your project. We're adding new tools every day! -Plus, you can [contact us](/faq/README.md#how-can-i-contact-the-meilisearch-team) if you need any help. We will answer for sure! +Plus, you can [contact us](/create/faq.md#how-can-i-contact-the-meilisearch-team) if you need any help. We will answer for sure! ## Do I need to configure MeiliSearch to get it working? @@ -43,15 +43,15 @@ MeiliSearch configuration works out-of-the-box. It means, by default, MeiliSearc For example, without requiring any configuration, MeiliSearch is typo tolerant. Type `craete an inedx` in the search bar of this documentation to experience the typo tolerance of our search engine. -To find out more about the relevancy of MeiliSearch, take a look at this detailed [explanation](/guides/main_concepts/relevancy.md#ranking-rules). +To find out more about the relevancy of MeiliSearch, take a look at this detailed [explanation](/learn/core_concepts/relevancy.md#ranking-rules). -However, MeiliSearch is of course [highly customizable](/references/settings.md) in order to adapt the search to your needs by setting synonyms, stop words, and custom ranking rules. +However, MeiliSearch is of course [highly customizable](/reference/api/settings.md) in order to adapt the search to your needs by setting synonyms, stop words, and custom ranking rules. ## How to know if MeiliSearch perfectly fits my use cases? -Since MeiliSearch is an open-source and easy-to-use tool, you can give it a try using your data. Follow this [guide](/guides/introduction/quick_start_guide.md) to get a quick start! +Since MeiliSearch is an open-source and easy-to-use tool, you can give it a try using your data. Follow this [guide](/learn/tutorials/getting_started.md) to get a quick start! -Besides, we published a [comparison between MeiliSearch and other search engines](/resources/comparison_to_alternatives.md) with the goal of providing an overview of MeiliSearch alternatives. +Besides, we published a [comparison between MeiliSearch and other search engines](/learn/what_is_meilisearch/comparison_to_alternatives.md) with the goal of providing an overview of MeiliSearch alternatives. ## Which languages can MeiliSearch handle? @@ -76,24 +76,24 @@ It means that in many cases (e.g., documents addition), you will receive as serv This kind of **successful response** indicates that the operation has been taken into account, but may not have been executed yet. ::: tip -You can check the status of the operation using the `updateId` via the [get update status route](/references/updates.md#get-an-update-status). -In addition, MeiliSearch delivers a global route to [track all your update status](/references/updates.md#get-all-update-status). +You can check the status of the operation using the `updateId` via the [get update status route](/reference/api/updates.md#get-an-update-status). +In addition, MeiliSearch delivers a global route to [track all your update status](/reference/api/updates.md#get-all-update-status). **This way, you will be informed if your action was processed or not, and why**. ::: -If you are curious about how the asynchronous part of MeiliSearch works, you can find more information [here](/guides/advanced_guides/asynchronous_updates.md). +If you are curious about how the asynchronous part of MeiliSearch works, you can find more information [here](/learn/advanced/asynchronous_updates.md). ## I am trying to add my documents but I keep receiving a `400 - Invalid data` response. MeiliSearch API only accepts JSON format. -In case of a [document addition](/references/documents.md#add-or-replace-documents), only an array of objects is expected. +In case of a [document addition](/reference/api/documents.md#add-or-replace-documents), only an array of objects is expected. The `400 - Invalid data` response probably means that your data is not in an expected format. Most common errors: - Extraneous comma at the end of a line. -- Data is not an array of objects: for the [document addition route](/references/documents.md#add-or-replace-documents), MeiliSearch only accepts an array in the body even if there is only one document. +- Data is not an array of objects: for the [document addition route](/reference/api/documents.md#add-or-replace-documents), MeiliSearch only accepts an array in the body even if there is only one document. Wrong: @@ -127,11 +127,11 @@ Most common reasons: Each document is required to contain a unique identifier. This identifier attribute is the `primary key`. -How do I know the primary key of my index? [Check this route](/references/indexes.md#get-one-index). The `null` value means it has not been defined yet. +How do I know the primary key of my index? [Check this route](/reference/api/indexes.md#get-one-index). The `null` value means it has not been defined yet. By default, the primary key will be inferred from the first document received. MeiliSearch will search for an attribute that contains the string `id` in a case-insensitive manner (e.g., `uid`, `MovieId`, `ID`, `123id123`). If none has been found, no documents will be added. -If you get a `document id is missing` error, the primary key was not recognized. This means your primary key is wrongly formatted. Sending primary key's name as a query parameter [when adding documents](/references/documents.md#add-or-replace-documents) should solve this issue. +If you get a `document id is missing` error, the primary key was not recognized. This means your primary key is wrongly formatted. Sending primary key's name as a query parameter [when adding documents](/reference/api/documents.md#add-or-replace-documents) should solve this issue. Note that the primary key value must contain only `A-Z a-z 0-9` and `-_` characters. @@ -147,17 +147,17 @@ Good: "id": "_Aabc012_" ``` -See more [information about the primary key](/guides/main_concepts/documents.md#primary-key). +See more [information about the primary key](/learn/core_concepts/documents.md#primary-key). ## I have uploaded my documents, but I get no result when I search in my index. Your documents upload probably failed. -To understand what happened, please check this [answer](/faq/README.md#i-did-a-call-to-an-api-route-and-i-only-got-an-updateid-as-a-response-what-does-it-mean). +To understand what happened, please check this [answer](/create/faq.md#i-did-a-call-to-an-api-route-and-i-only-got-an-updateid-as-a-response-what-does-it-mean). ## Is killing a MeiliSearch process safe? Killing MeiliSearch is **safe**, even in the middle of a process (ex: adding a batch of documents). When you restart the server, it will start the task from the beginning. -More information in the [asynchronous updates guide](/guides/advanced_guides/asynchronous_updates.md). +More information in the [asynchronous updates guide](/learn/advanced/asynchronous_updates.md). ## Does MeiliSearch deliver an interface to search in my documents? @@ -165,17 +165,17 @@ Yes, a web interface is available on the default address and port of your MeiliS All you need to do is open your web browser and enter MeiliSearch’s address to visit it. This leads you to a web page with a search bar that allows you to search in a selected index. -Since the production environment requires an API-key for searching, the web interface is only available in [development mode](/guides/advanced_guides/configuration.md#environment). +Since the production environment requires an API-key for searching, the web interface is only available in [development mode](/reference/features/configuration.md#environment). -Here is more information about the [MeiliSearch web interface](/guides/advanced_guides/web_interface.md). +Here is more information about the [MeiliSearch web interface](/reference/features/web_interface.md). ## I do not understand the relevancy of my search results. The search responses are sorted according to a set of consecutive rules called ranking rules. -Here is more information about the [relevancy of MeiliSearch](/guides/main_concepts/relevancy.md). +Here is more information about the [relevancy of MeiliSearch](/learn/core_concepts/relevancy.md). MeiliSearch applies these ranking rules in default order. This order can be modified. Furthermore, these rules can be deleted and new ones can be added. -All of the ranking rules can be modified via the [dedicated routes in the MeiliSearch API](/references/ranking_rules.md). +All of the ranking rules can be modified via the [dedicated routes in the MeiliSearch API](/reference/api/ranking_rules.md). ## Do you provide a public roadmap for MeiliSearch and its integration tools? @@ -185,7 +185,7 @@ For more accurate features and issues, everything is detailed in the issues of a ## How can I contact the MeiliSearch team? -See our [contact page](/resources/contact.md). +See our [contact page](/learn/what_is_meilisearch/contact.md). ## I have just updated MeiliSearch, and I am getting an error: "Cannot open database, expected MeiliSearch engine version..." diff --git a/create/how_to/README.md b/create/how_to/README.md new file mode 100644 index 0000000000..d6fb6a46e6 --- /dev/null +++ b/create/how_to/README.md @@ -0,0 +1,16 @@ +# How To + +These how-to guides take the reader through the steps required to solve a real-world problem. Like recipes in a cookbook, they represent repeatable solutions to particular problems. + +This is not the section for tutorial content. If you'd like to follow a step-by-step tutorial that introduces you to the basics of MeiliSearch, check out our [getting started guide](/learn/tutorials/getting_started.md). + +## Table of Contents + +How to: + +- [Run MeiliSearch in Production](/create/how_to/running_production.md) +- [Integrate a Relevant Search Bar to Your Documentation](/create/how_to/search_bar_for_docs.md) +- [Deploy MeiliSearch on DigitalOcean](/create/how_to/digitalocean_droplet.md) +- [Use HTTP/2 and SSL with MeiliSearch](/create/how_to/http2_ssl.md) +- [Use Postman with MeiliSearch](/create/how_to/postman_collection.md) +- [Implement Instant Search in Your React App in 5 Minutes](/create/how_to/meilisearch_react.md) diff --git a/resources/howtos/digitalocean_droplet.md b/create/how_to/digitalocean_droplet.md similarity index 98% rename from resources/howtos/digitalocean_droplet.md rename to create/how_to/digitalocean_droplet.md index 10676e7849..522215b657 100644 --- a/resources/howtos/digitalocean_droplet.md +++ b/create/how_to/digitalocean_droplet.md @@ -1,4 +1,4 @@ -# How to deploy a MeiliSearch instance on DigitalOcean +# Deploy a MeiliSearch Instance on DigitalOcean ## Create an out-of-the-box MeiliSearch diff --git a/resources/howtos/http2_ssl.md b/create/how_to/http2_ssl.md similarity index 99% rename from resources/howtos/http2_ssl.md rename to create/how_to/http2_ssl.md index a94413cfd0..a81e5057c1 100644 --- a/resources/howtos/http2_ssl.md +++ b/create/how_to/http2_ssl.md @@ -2,7 +2,7 @@ permalink: /http2-ssl --- -# How to use HTTP/2 and SSL with MeiliSearch +# Use HTTP/2 and SSL with MeiliSearch For those willing to use HTTP/2, please be aware that it is **only possible if your server is configured with SSL certificate**. diff --git a/resources/howtos/meilisearch_react.md b/create/how_to/meilisearch_react.md similarity index 96% rename from resources/howtos/meilisearch_react.md rename to create/how_to/meilisearch_react.md index 3f636d7a91..722c1bb89a 100644 --- a/resources/howtos/meilisearch_react.md +++ b/create/how_to/meilisearch_react.md @@ -1,7 +1,7 @@ --- permalink: /instant-search-react-app --- -# How to implement Instant Search within 5 minutes in your React App +# Implement Instant Search in Your React App in 5 Minutes _The following is a guest post by Riccardo Giorato._ @@ -60,7 +60,7 @@ You will be able to check that MeiliSearch is running by visiting the following An index is an entity in which documents are stored, like an array of objects with some specific settings attached to it and a unique primary key. -You can read more about the properties of [indexes](https://docs.meilisearch.com/guides/main_concepts/indexes.html) in the the MeiliSearch documentation. +You can read more about the properties of [indexes](/learn/core_concepts/indexes.md) in the the MeiliSearch documentation. In order to create your index, you need to find out what your primary key is. Below is a sample document to add to MeiliSearch. @@ -344,7 +344,7 @@ With MeiliSearch, you get a ton of other small options you can fine-tune to impr ### Search Ranking -Start by changing the search rankings, or more simply, the way MeiliSearch looks through the documents you uploaded to find the references to your search terms inside the [rankingRules](/guides/main_concepts/relevancy.md#relevancy) object. In that case, set the following ranking: +Start by changing the search rankings, or more simply, the way MeiliSearch looks through the documents you uploaded to find the references to your search terms inside the [rankingRules](/learn/core_concepts/relevancy.md#relevancy) object. In that case, set the following ranking: - "typo" - "words" @@ -358,7 +358,7 @@ This configuration is the default one except for the last field which is a custo ### Searchable Attributes -Secondly, you have to specify the attributes that MeiliSearch can search from in each document, inside a [searchableAttributes](/guides/advanced_guides/field_properties.md#searchable-fields) object. Here, the configuration is done to search only on name, vendor, category and tags leaving out images or URL. +Secondly, you have to specify the attributes that MeiliSearch can search from in each document, inside a [searchableAttributes](/reference/features/field_properties.md#searchable-fields) object. Here, the configuration is done to search only on name, vendor, category and tags leaving out images or URL. ### Displayed Attributes diff --git a/resources/postman_collection.md b/create/how_to/postman_collection.md similarity index 91% rename from resources/postman_collection.md rename to create/how_to/postman_collection.md index 59726efa2d..99051446e6 100644 --- a/resources/postman_collection.md +++ b/create/how_to/postman_collection.md @@ -34,6 +34,6 @@ The `url` and `indexUID` variables are used in all the collection routes, like i ## Start to use it! -You can now [run your MeiliSearch instance](/guides/advanced_guides/installation.md) and create your first index: +You can now [run your MeiliSearch instance](/reference/features/installation.md) and create your first index: ![Create index](/postman/create_index.png) diff --git a/resources/tutorials/running_production.md b/create/how_to/running_production.md similarity index 91% rename from resources/tutorials/running_production.md rename to create/how_to/running_production.md index 556a6ecaaa..d627be6ccb 100644 --- a/resources/tutorials/running_production.md +++ b/create/how_to/running_production.md @@ -1,31 +1,31 @@ --- permalink: /running-production --- -# MeiliSearch in production: taking it to the next level +# Run MeiliSearch in Production: taking it to the next level ## A quick introduction Hopefully, you already know that [MeiliSearch](https://github.com/meilisearch/MeiliSearch) is a powerful and fast open-source search engine built in [Rust](https://www.rust-lang.org). It was designed to provide users with a very useful and customizable search experience including out-of-the-box features such as typo-tolerance, filtering, and synonyms for any kind of project. -Running a Meilisearch instance for testing purposes is incredibly easy and can be done in [many ways](https://docs.meilisearch.com/guides/introduction/quick_start_guide.html): using Docker, Homebrew, Aptitude, binaries, a simple `curl`, or even the source code. If you are new to MeiliSearch, we suggest that you take a tour around the documentation. +Running a Meilisearch instance for testing purposes is incredibly easy and can be done in [many ways](/learn/tutorials/getting_started.md): using Docker, Homebrew, Aptitude, binaries, a simple `curl`, or even the source code. If you are new to MeiliSearch, we suggest that you take a tour around the documentation. Using MeiliSearch on your own machine for your weekend project is fun, let's agree on that. However, you may want to go live and deploy a project in production, to take it to the next level. What steps and details would you need to **deploy MeiliSearch in production** and ensure it is **safe and ready to use**? ## Content of this article -[Step 1: Install MeiliSearch](/resources/tutorials/running_production.md#step-1-install-meilisearch) +[Step 1: Install MeiliSearch](/create/how_to/running_production.md#step-1-install-meilisearch) -[Step 2: Run MeiliSearch as a service](/resources/tutorials/running_production.md#step-2-run-meilisearch-as-a-service) +[Step 2: Run MeiliSearch as a service](/create/how_to/running_production.md#step-2-run-meilisearch-as-a-service) -+ [2.1 Create a service file](/resources/tutorials/running_production.md#_2-1-create-a-service-file) -+ [2.2. Enable and start service](/resources/tutorials/running_production.md#_2-2-enable-and-start-service) ++ [2.1 Create a service file](/create/how_to/running_production.md#_2-1-create-a-service-file) ++ [2.2. Enable and start service](/create/how_to/running_production.md#_2-2-enable-and-start-service) -[Step 3: Secure and finish your setup. Using a Reverse Proxy, domain name and HTTPS](/resources/tutorials/running_production.md#step-3-secure-and-finish-your-setup-using-a-reverse-proxy-domain-name-and-https) +[Step 3: Secure and finish your setup. Using a Reverse Proxy, domain name and HTTPS](/create/how_to/running_production.md#step-3-secure-and-finish-your-setup-using-a-reverse-proxy-domain-name-and-https) -+ [3.1. Creating a Reverse Proxy with Nginx](/resources/tutorials/running_production.md#_3-1-creating-a-reverse-proxy-with-nginx) -+ [3.2. Set up SSL/TLS for your MeiliSearch](/resources/tutorials/running_production.md#_3-2-set-up-ssl-tls-for-your-meilisearch) ++ [3.1. Creating a Reverse Proxy with Nginx](/create/how_to/running_production.md#_3-1-creating-a-reverse-proxy-with-nginx) ++ [3.2. Set up SSL/TLS for your MeiliSearch](/create/how_to/running_production.md#_3-2-set-up-ssl-tls-for-your-meilisearch) -[Conclusion](/resources/tutorials/running_production.md#conclusion) +[Conclusion](/create/how_to/running_production.md#conclusion) ## Get your MeiliSearch ready for production @@ -53,7 +53,7 @@ $ apt install curl -y $ curl -L https://install.meilisearch.com | sh ``` -> The different options to achieve a MeiliSearch installation are detailed in **[this guide](https://docs.meilisearch.com/guides/advanced_guides/installation.html#download-and-launch)**. +> The different options to achieve a MeiliSearch installation are detailed in **[this guide](/reference/features/installation.md#download-and-launch)**. > It is important to know that there are different ways to get MeiliSearch running on your machine. As an open source project, you can always compile the latest stable release of MeiliSearch from the source code to ensure the binary uses your achitecture in the best possible way. You can always check the latest MeiliSearch stable version, and get MeiliSearch for the Operating System of your choice, by visiting the following link: @@ -115,7 +115,7 @@ WantedBy=default.target EOF ``` -> For more information on MeiliSearch authentication and API keys see the **[Authentication Docs](https://docs.meilisearch.com/guides/advanced_guides/authentication.html)**. For more information on MeiliSearch options and flags see the **[Installation Docs](https://docs.meilisearch.com/guides/advanced_guides/installation.html#download-and-launch)** +> For more information on MeiliSearch authentication and API keys see the **[authentication docs](/reference/features/authentication.md)**. For more information on MeiliSearch options and flags see the **[installation docs](/reference/features/installation.md#download-and-launch)** As for now, it is not time yet to expose your MeiliSearch instance to the external world. To keep running it safely inside your own environment, make it available locally at `127.0.0.1`. This means that only programs running on your machine are allowed to make requests to your MeiliSearch instance. @@ -304,6 +304,6 @@ Your SSL certificates should be working and Nginx should be able to find them. E You have followed the main steps to provide a safe and stable service. Your MeiliSearch instance should be up and running, in a safe environment and ready to stay available even when the most common issues occur. In addition, it is protected by a reverse proxy with your own domain name and API key, so your data and configuration are accessible only to trusted clients. Communication with your server is now encrypted. Furthermore, its identity will be verified every time before sending sensitive data in a fast and automated manner. -You are now ready to start using your **Production-ready MeiliSearch**! +You are now ready to start using your **production-ready MeiliSearch instance**! > MeiliSearch is a database which means that it needs a file system it can write to, and which must be persistent. diff --git a/resources/howtos/search_bar_for_docs.md b/create/how_to/search_bar_for_docs.md similarity index 91% rename from resources/howtos/search_bar_for_docs.md rename to create/how_to/search_bar_for_docs.md index 5a0ba6997a..6f555a1971 100644 --- a/resources/howtos/search_bar_for_docs.md +++ b/create/how_to/search_bar_for_docs.md @@ -23,7 +23,7 @@ $ curl -L https://install.meilisearch.com | sh $ ./meilisearch --master-key=myMasterKey ``` -There are [other ways to install MeiliSearch](/guides/introduction/quick_start_guide.md#download-and-launch). +There are [other ways to install MeiliSearch](/learn/tutorials/getting_started.md#download-and-launch). MeiliSearch is open-source and can run either on your server or on any cloud provider. @@ -90,7 +90,7 @@ More [optional fields are available](https://github.com/meilisearch/docs-scraper ### Run the Scraper -You can run the scraper with Docker. With our local MeiliSearch instance set up at [the first step](./search_bar_for_docs.md#run-a-meilisearch-instance), we run: +You can run the scraper with Docker. With our local MeiliSearch instance set up at [the first step](#run-a-meilisearch-instance), we run: ```bash $ docker run -t --rm \ @@ -107,10 +107,10 @@ If you don't want to use Docker, here are [other ways to run the scraper](https: ::: -`` should be the **absolute** path of your configuration file defined at [the previous step](./search_bar_for_docs.md#configuration-file). +`` should be the **absolute** path of your configuration file defined at [the previous step](#configuration-file). The API key you must provide should have the permissions to add documents into your MeiliSearch instance. In a production environment, we recommend providing the private key instead of the master key, as it is safer and it has enough permissions to perform such requests. -_More about [MeiliSearch authentication](/guides/advanced_guides/authentication.md)._ +_More about [MeiliSearch authentication](/reference/features/authentication.md)._ ::: tip @@ -154,14 +154,14 @@ module.exports = { ``` The `hostUrl` and the `apiKey` fields are the credentials of the MeiliSearch instance. Following on from this tutorial, they are respectively `http://localhost:7700` and `myMasterKey`. -`indexUid` is the index identifier in your MeiliSearch instance in which your website content is stored. It has been defined in the [config file](./search_bar_for_docs.md#configuration-file). +`indexUid` is the index identifier in your MeiliSearch instance in which your website content is stored. It has been defined in the [config file](#configuration-file). These three fields are mandatory, but more [optional fields are available](https://github.com/meilisearch/vuepress-plugin-meilisearch#customization) to customize your search bar. ::: warning Since the configuration file is public, we strongly recommend providing the MeiliSearch public key in a production environment, which is enough to perform search requests. -Read more about [MeiliSearch authentication](/guides/advanced_guides/authentication.md). +Read more about [MeiliSearch authentication](/reference/features/authentication.md). ::: @@ -195,13 +195,13 @@ If you don't use VuePress for your documentation, we provide a [front-end SDK](h ``` The `hostUrl` and the `apiKey` fields are the credentials of the MeiliSearch instance. Following on from this tutorial, they are respectively `http://localhost:7700` and `myMasterKey`. -`indexUid` is the index identifier in your MeiliSearch instance in which your website content is stored. It has been defined in the [config file](./search_bar_for_docs.md#configuration-file). +`indexUid` is the index identifier in your MeiliSearch instance in which your website content is stored. It has been defined in the [config file](#configuration-file). `inputSelector` is the `id` attribute of the HTML search input tag. ::: warning We strongly recommend providing the MeiliSearch public key in a production environment, which is enough to perform search requests. -Read more about [MeiliSearch authentication](/guides/advanced_guides/authentication.md). +Read more about [MeiliSearch authentication](/reference/features/authentication.md). ::: @@ -216,4 +216,4 @@ For more concrete examples, you can check out this [basic HTML file](https://git ## What's next? At this point you should have a working search engine on your website, congrats! 🎉 -You can check [this tutorial](/resources/tutorials/running_production.md) if you now want to run MeiliSearch in production! +You can check [this tutorial](/create/how_to/running_production.md) if you now want to run MeiliSearch in production! diff --git a/guides/README.md b/guides/README.md deleted file mode 100644 index d8d4d09378..0000000000 --- a/guides/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# MeiliSearch Guides - -## 🧘‍♀️ Philosophy & usage of MeiliSearch - -MeiliSearch aims to be your go-to search backend when you want to build a great search experience for your end-users. -MeiliSearch is designed for end-user search in a not-so-big data collection (< 10M documents). -MeiliSearch is made for [type-as-you-search](https://en.wikipedia.org/wiki/Incremental_search) and [prefix-search](https://en.wikipedia.org/wiki/Trie). - -## ⛔️ Anti-pattern - -MeiliSearch should **not be your main data store**. MeiliSearch should contain only the data you want your users to search through. The more data MeiliSearch contains, the less relevant it is. - -MeiliSearch queries should be sent directly from the front-end. The more proxy there is between MeiliSearch and the end-user, the less fast queries and thus search-experience will be. - -## 🎲 Guides - -The aim of these guides is to provide an overview of MeiliSearch. For each important notion, pages to detailed and expanded explanations have been linked. - -Content: - -- [🚀 Introduction](/guides/introduction/): Starting with MeiliSearch! -- [💡 Main Concepts](/guides/main_concepts/): Understanding the basics like indexes, documents and searches. -- [📚 Advanced Guides](/guides/advanced_guides/): Deep diving into the advanced but accessible concepts of MeiliSearch. - -::: note -This [documentation is completely open-source](https://github.com/meilisearch/documentation). We keep it up-to-date but you might find some typos or mistakes. Help us make it a better guide by submitting a pull request or [an issue](https://github.com/meilisearch/documentation/issues) 😁 -::: diff --git a/guides/advanced_guides/README.md b/guides/advanced_guides/README.md deleted file mode 100644 index 57eb241738..0000000000 --- a/guides/advanced_guides/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# Advanced guides - -These advanced guides cover how to tune your search API and customize it: - -- [How to install MeiliSearch](installation.md) -- [Configure your MeiliSearch](configuration.md) -- [Search parameters](search_parameters.md) -- [Authentication](authentication.md) -- [Settings Configuration](settings.md) -- [Synonyms](synonyms.md) -- [Stop words](stop_words.md) -- [Distinct Attribute](distinct.md) -- [Field properties](field_properties.md) -- [Snapshots and Dumps](snapshots_and_dumps.md) - -To learn how MeiliSearch works under the hood and better understand the algorithms behind it, you can read the following advanced guides: - -- [Asynchronous updates](asynchronous_updates.md) -- [Web interface](web_interface.md) -- [Typo Tolerance](typotolerance.md) -- [Prefix Search](prefix.md) -- [Concatenate and Split Queries](concat.md) -- [Bucket sort](bucket_sort.md) diff --git a/guides/advanced_guides/snapshots_and_dumps.md b/guides/advanced_guides/snapshots_and_dumps.md deleted file mode 100644 index 4be42a47fe..0000000000 --- a/guides/advanced_guides/snapshots_and_dumps.md +++ /dev/null @@ -1,118 +0,0 @@ -# Snapshots and Dumps - -## Snapshot vs Dump - -MeiliSearch has two ways to backup its data: `snapshots` and `dumps`. - -**Snapshots** make it possible to schedule the creation of hard copies of your database. This feature is **intended mainly as a safeguard**: ensuring that if some failure occurs, you're able to relaunch your database quickly and efficiently from a snapshot. The documents in a snapshot are already "indexed" and ready to go, greatly increasing import speed. However, as a result, **snapshots are not compatible between different versions of MeiliSearch**. - -Dumps, on the other hand, export MeiliSearch data in a way that is not bound to a specific MeiliSearch version. As a result, importing a dump requires MeiliSearch to index all of your documents. This process requires a certain amount of time and memory (corresponding to the number of documents, their size, and the complexity of any index settings). - -**To summarize**, snapshots are highly efficient but not portable between different versions of MeiliSearch. Dumps, on the other hand, are highly portable but not very efficient, as frequently launching MeiliSearch from a dump would cause your performance to suffer. - -## Snapshots - -A snapshot is an exact copy of the database (i.e. the data.ms folder) at the time the snapshot was created. Besides compression, snapshots do not go through any processing. They can be thought of as "pre-compiled copies". -Using this feature, it is possible to schedule snapshot creation at custom intervals and use existing snapshots to restore MeiliSearch. - -### Creating Snapshots - -For MeiliSearch to create snapshots, the feature must be enabled by adding the following flag: - -```bash -$ meilisearch --schedule-snapshot=true -``` - -By default, MeiliSearch creates snapshots in a directory called `snapshots/` at the root of your MeiliSearch. - -The destination can be modified with the `--snapshot-dir` flag. - -```bash -$ meilisearch --schedule-snapshot=true --snapshot-dir mySnapShots/ -``` - -Now snapshots are created in `mySnapShots/` directory. - -The first snapshot is created on launching MeiliSearch. After that, snapshots are created routinely on a set interval until you deactivate snapshots or end the MeiliSearch instance. By default, one snapshot is taken every 24 hours. - -The amount of time between each new snapshot can be modified with the `--snapshot-interval-sec` flag. - -```bash -$ meilisearch --schedule-snapshot=true --snapshot-interval-sec 3600 -``` - -After running the above code, a snapshot is created every hour (3600 seconds). - -During snapshot creation, old snapshots are **automatically overwritten**. This means that only the most recent snapshot should be present in the folder at any given time. - -[[More about snapshots flags and env variables]](/guides/advanced_guides/configuration.md#schedule-snapshot-creation) - -### Start from Snapshot - -Because snapshots are exact copies of your database that haven't gone through any processing besides compression, starting a MeiliSearch instance from a snapshot is significantly faster than adding documents manually or starting from a dump. - -Using the global environment `MEILI_IMPORT_SNAPSHOT` or the CLI flag `--import-snapshot` , MeiliSearch will start the server using the provided snapshot. - -```bash -$ meilisearch --import-snapshot mySnapShots/data.ms.snapshot -``` - -#### Common Problems - -Take note that whenever you launch MeiliSearch from a snapshot, it will *stop processing and throw an error** if it encounters either of the two following situations: - -1. A database already exists (i.e. you have a non-empty `data.ms` folder in the same directory as your MeiliSearch binary) -2. No snapshot is found at the given path - -In both cases, **this behavior is [configurable](/guides/advanced_guides/configuration.md#ignore-missing-snapshot)**. - -If you don't want MeiliSearch to throw an error when finding that a database already exists, you can add the following flag: `--ignore-snapshot-if-db-exists=true`. When using this flag, MeiliSearch will use the existing database to start an instance instead of throwing an error. The snapshot will be ignored. - -If you do not want MeiliSearch to throw an error when there is no snapshot at the given path, you can add the following flag: `--ignore-missing-snapshot`. MeiliSearch will then continue its process and not import any snapshot. - -When starting from a snapshot, chances are that you already have an existing database. **For security reasons, a database is never overwritten**. To load a snapshot when an existing database is present, you will have to manually delete the existing database. By default, this is the contents of the `data.ms` folder (unless you [changed the path](/guides/advanced_guides/configuration.md#database-path)) which is located in the same folder as your MeiliSearch binary. -The simplest way to delete your database is with the terminal command `rm -rf data.ms`, after which you should be able to start MeiliSearch with a snapshot. - -[[More about snapshots flags and env variables]](/guides/advanced_guides/configuration.md#schedule-snapshot-creation) - -### Use Cases - -**Snapshots are safeguards in case of problems**. If your MeiliSearch instance encounters a problem or if you make a mistake while manipulating your database, restarting your instance with the latest snapshot is an easy way to recover your data. - -### Version Compatibility - -Since a snapshot is an exact replica of your database, it can only be opened by the same version of MeiliSearch that created it. - -## Dumps - -A dump is a compressed file containing an export of your MeiliSearch instance. It contains all your indexes, documents, and settings, but in a raw unprocessed form. A dump isn't an exact copy of your database—it is closer to a blueprint that allows you to create an identical dataset. A dump can be imported when launching MeiliSearch, but be advised that it may take some time to index all the documents within. - -### Creating a Dump - -To create a dump of your dataset, you need to use the appropriate HTTP route: `POST /dumps`. Using that route will trigger a dump creation process. Creating a dump is an asynchronous task that takes time based on the size of your dataset. A dump uid (unique identifier) is returned to help you track the process. - - - -The above code triggers a dump creation process. - -At any given moment, you can check the status of a particular dump creation process using the previously received dump uid, like so: `GET /dumps/:dump_uid/status`. Using this route, you can know whether your dump is still processing, has already been created, or has encountered a problem. - - - -After your dump creation process is done, the dump file is created and added in the dump folder. By default, this folder is `/dumps` at the root of your MeiliSearch binary, but this can be customized. Note that **if your dump folder does not already exist when the dump creation process is called, MeiliSearch will create it**. - -### Import a Dump - -Once you have exported a dump, which is a `.dump` file, you are now able to use that dump to launch MeiliSearch. As the data contained in the dump needs to be indexed, the process will take some time to complete. Only when the dump has been fully imported will the MeiliSearch server start, after which you can begin searching through your data. - -```bash -./meilisearch --import-dump /dumps/20200813-042312213.dump -``` - -Because importing a dump is the same process as when documents are initially indexed by MeiliSearch, it can require some time and memory. If your dataset is very large, it is good practice to index documents in larger batches. This will speed up the indexing process at the cost of memory. - -[See here for more dumps options](/guides/advanced_guides/configuration.md#dumps-destination) - -### Use Cases - -Dumps are used to restore your database after MeiliSearch updates or to communicate your database to other instances of MeiliSearch (e.g. running on different servers) without having to worry about their respective versions. diff --git a/guides/advanced_guides/tokenization.md b/guides/advanced_guides/tokenization.md deleted file mode 100644 index af42de26b6..0000000000 --- a/guides/advanced_guides/tokenization.md +++ /dev/null @@ -1,49 +0,0 @@ -# Language and Tokenization - -## Tokenization - -**Tokenization** is the act of taking a sentence or phrase and splitting it into smaller units of language, called tokens. It is the first step of document indexing in the Meilisearch engine, and is a critical factor in the quality of search results. - -Breaking sentences into smaller chunks requires understanding where one word ends and another begins, making tokenization a highly complex and language-dependant task. MeiliSearch's solution to this problem is a **modular tokenizer** that follows different processes, called **pipelines**, based on the language it detects. - -This allows MeiliSearch to function in several different languages with zero setup. - -### Deep Dive: The Meili Tokenizer - -![Tokenizer Architecture](https://user-images.githubusercontent.com/6482087/102896344-8560d200-4466-11eb-8cfe-b4ae8741093b.jpg) - -When you add documents to a MeiliSearch index, the tokenization process is handled by an abstract interface called an **analyzer**. The analyzer is responsible for determining the primary language of each based on the scripts (e.g. Latin alphabet, Chinese hanzi, etc.) that are present there. Then, it applies the corresponding **pipeline** to each field. - -We can break down the tokenization process like so: - -1. Crawl the document(s) and determine the primary language for each field. -2. Go back over the documents field-by-field, running the corresponding tokenization pipeline, if it exists. - -Pipelines include many language-specific operations. Currently, we have two pipelines: - -1. A specialized Chinese pipeline using [Jieba](https://github.com/messense/jieba-rs) -2. A default MeiliSearch pipeline that separates words based on categories. Works with a variety of languages. - -For more details, check out the [feature specification](https://github.com/meilisearch/specifications/blob/master/text/0001-script-based-tokenizer.md). - -## Language Support - -**MeiliSearch is multilingual**, featuring optimized support for: - -- **Any language that uses whitespace to separate words** -- **Chinese** 🇨🇳 (through [Jieba](https://github.com/messense/jieba-rs)) - -We aim to provide global language support, and your feedback helps us [move closer to that goal](/guides/advanced_guides/tokenization.md#improving-our-language-support). If you notice inconsistencies in your search results or the way your documents are processed, please open an issue on our [GitHub repository](https://github.com/meilisearch/MeiliSearch/issues/new/choose). - -### Improving Our Language Support - -While we have employees from all over the world at MeiliSearch, we don't speak every language. In fact, we rely almost entirely on feedback from external contributors to know how our engine is performing across different languages. - -If you'd like to help us create a more global MeiliSearch, please consider sharing your tests, results, and general feedback with us through [GitHub issues](https://github.com/meilisearch/MeiliSearch/issues). Here are some of the languages that have been requested by users and their corresponding issue: - -- [Arabic](https://github.com/meilisearch/MeiliSearch/issues/554) -- [Lao](https://github.com/meilisearch/MeiliSearch/issues/563) -- [Persian/Farsi](https://github.com/meilisearch/MeiliSearch/issues/553) -- [Thai](https://github.com/meilisearch/MeiliSearch/issues/864) - -If you'd like us to add or improve support for a language that isn't in the above list, please create an [issue](https://github.com/meilisearch/MeiliSearch/issues/new?assignees=&labels=&template=feature_request.md&title=) saying so, and then make a [pull request on the documentation](https://github.com/meilisearch/documentation/edit/master/guides/advanced_guides/tokenization.md) to add it to the above list. diff --git a/guides/introduction/README.md b/guides/introduction/README.md deleted file mode 100644 index 9c8a95d56f..0000000000 --- a/guides/introduction/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Introduction - -MeiliSearch has been developed to provide an easily integrated search solution. Each step of the implementation process has been designed to be **as simple as possible**. - -Contents : - -- 🚀 Getting Started - - [Download and launch MeiliSearch](/guides/introduction/quick_start_guide.md#download-and-launch) - - [Add documents](/guides/introduction/quick_start_guide.md#add-documents) - - [Search!](/guides/introduction/quick_start_guide.md#search) -- 👩‍🚀 [What's next?](/guides/introduction/whats_next.md) diff --git a/guides/introduction/whats_next.md b/guides/introduction/whats_next.md deleted file mode 100644 index 3986d7b0a9..0000000000 --- a/guides/introduction/whats_next.md +++ /dev/null @@ -1,20 +0,0 @@ -# What's next? - -MeiliSearch was built on a few core concepts. If you haven't already done so, we invite you to explore the following pages that will give you an essential insight into our search engine: - -- [Indexes](/guides/main_concepts/indexes.md) -- [Documents](/guides/main_concepts/documents.md) -- [Search](/guides/main_concepts/search.md) -- [Relevancy](/guides/main_concepts/relevancy.md) - -You can find the API references here: - -- [API References](/references/README.md) - -And additional resources here: - -- [SDKs](/resources/sdks.md) -- [FAQ](/faq/) -- [Postman collection](/resources/postman_collection.md): it can be tedious to re-write every route when wanting to try out an API. Try out MeiliSearch with our collection in Postman - -Tutorials and Cookbooks are currently being prepared. They will be available soon. diff --git a/guides/main_concepts/README.md b/guides/main_concepts/README.md deleted file mode 100644 index 9cdcb9a5fc..0000000000 --- a/guides/main_concepts/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Main Concepts - -This section defines the main concepts of MeiliSearch. - -::: tip Important -MeiliSearch is an **asynchronous** API. This means that, unlike a synchronous API, it doesn't wait for the call to be done as calls are placed in a queue for processing. For further information please read [the advanced guide](/guides/advanced_guides/asynchronous_updates.md). -::: - -## Glossary - -The following key terms are used in this documentation. Before going any further, it is recommended to become familiar with them. - -- **[Index](indexes.md)**: An index is the entity that gathers all the documents of a given structure. It can be comparable to a table in `SQL`. -- **[Document](documents.md)**: A document is an object which contains defined attributes and their associated data. diff --git a/guides/main_concepts/search.md b/guides/main_concepts/search.md deleted file mode 100644 index 4f7df0d3ae..0000000000 --- a/guides/main_concepts/search.md +++ /dev/null @@ -1,89 +0,0 @@ -# Search - -MeiliSearch has been designed to improve your search experience. - -Today, finding a high-quality search engine may be complicated. Because we realized there was a lack of both powerful and simple solutions, we decided to create MeiliSearch. The **simplicity of use** is our philosophy and it keeps driving the development of MeiliSearch. - -## Simple and Intuitive - -We aimed for a simple and intuitive experience for both developers and end-users. - -For developers, it requires very little configuration to be up and running. Communication to the server is done through a [RESTful API](/references/README.md). - -For users, the search experience aims to feel simple so they can focus on the results. MeiliSearch delivers an intuitive search-as-you-type experience; which means a response time lower than 50 milliseconds. - -## Highly Customizable - -MeiliSearch works out-of-the-box with default settings that meet the needs of most projects. - -However, searching is highly customizable. - -> It would not be a search engine if there wasn't a notion of relevancy in the results returned. - -The returned results are **sorted according to a set of consecutive rules called [ranking rules](/guides/main_concepts/relevancy.md#ranking-rules)**. You can delete existing rules, add new ones, or even change the order in which they are executed. - -You can also **configure the [search parameters](/guides/advanced_guides/search_parameters.md)** to refine your search even further. We support [filters](/guides/advanced_guides/filtering.md) and [faceting](/guides/advanced_guides/faceted_search.md). - -## Features - -![search demo gif](/search-synonyms-typo.gif) - -> MeiliSearch in action with `batman` and `joker` being defined as synonyms. - -All of MeiliSearch's features are provided out-of-the-box and can be easily [configured](/guides/advanced_guides/search_parameters.md). Here is a few of them that you should try out: - -### Search as you type - -Also called instant search, results are displayed while you are still inputting your query. Showed results are changed in real-time whenever you type additional text in the search box. - -### Typo tolerance - -Instead of letting typos ruin your search experience, MeiliSearch will find the results you expect. -Read more about [typo tolerance in this dedicated guide](/guides/advanced_guides/typotolerance.md). - -### Synonyms - -Search should not be limited by some specific words. -Read more about [synonyms in this dedicated guide](/guides/advanced_guides/synonyms.md). - -### Languages support - -MeiliSearch supports Latin-based languages, English, and Kanji characters. - -### Highlighting - -Search results can contain [highlighted](/guides/advanced_guides/search_parameters.md#attributes-to-highlight) queried terms to further enhance usability. Users don't need to read the entire text. The terms are highlighted and thus catch their eye. - -### Filters - -Meilisearch allows you to define [filters](/guides/advanced_guides/filtering.md) so you can filter through the results based on criteria. - -### Faceting - -[Faceted search](/guides/advanced_guides/faceted_search.md) is a feature provided out-of-the-box by MeiliSearch. It allows you to classify search results into categories and to build intuitive navigation interfaces. - -### Placeholder Search - -If you make a search without inputting any query words, MeiliSearch will return all the documents in that index sorted by its [custom ranking rules](/guides/advanced_guides/settings.md#custom-ranking-rule). This feature is called **placeholder search**. It is particularly effective when used with other features such as [faceting or filtering](/guides/advanced_guides/faceted_search.md#filters-or-facets), which allow users to narrow their searches and browse by category. - -Placeholder search is not affected by MeiliSearch's [default ranking rules](/guides/advanced_guides/settings.md#ranking-rules)—only custom rules added by a user. If no custom rules have been set, the results are displayed in the order of their internal database position. - -### Examples - -Here are a few examples of what can be achieved with the [search parameters](/guides/advanced_guides/search_parameters.md): - -Results can be paginated using the `limit` and `offset` query parameters. - - - -You can filter results using the `filters` query parameter. - - - -## Give it a try! - -Instead of showing you examples, why not just invite you to test MeiliSearch interactively in the **out-of-the-box web interface** we deliver? - -There's no need to write a single line of front-end code. All you need to do is follow [this guide](/guides/advanced_guides/web_interface.md) to give the search engine a try! - -![web interface](/web-interface.png) diff --git a/index.md b/index.md index 8496ae8226..016472af51 100644 --- a/index.md +++ b/index.md @@ -1,46 +1,48 @@ # MeiliSearch Documentation -MeiliSearch is a **RESTful search API**. It aims to be a **ready-to-go solution** for everyone who wants a **fast and relevant search experience** for their end-users ⚡️🔎 +Welcome to the MeiliSearch documentation. Here you'll find everything you need to learn and create with our **lightning fast search engine**. -[](/guides/introduction/quick_start_guide.md) +[](/learn/what_is_meilisearch) -Efficient search engines often require a significant investment of resources. They are only accessible to companies with the means necessary to develop a bespoke search solution that fits their needs. +If you're looking for information on a specific MeiliSearch SDK or front-end integration, you'll find it in our [SDK list](/learn/what_is_meilisearch/sdks.md). -Small to medium sized businesses commonly resort to subpar search engines that incur invisible costs on their user experience and retention due to poor search fulfillment. +## Getting Started -That's why we created MeiliSearch: An open source solution accessible to everyone, designed to meet a vast majority of needs. Requiring very little configuration to be installed, yet highly customizable. +**Enjoy a hands-on approach to learning**? Follow a [quick tutorial](/learn/tutorials/getting_started.md) to learn the basics of the engine. -Our solution delivers an **instant search experience**; it handles **typos**; it understands **filters**, **custom rankings**, and many other [features](#features). +**Prefer to learn by reading**? You're not alone. Check out articles covering the most important [core concepts](/learn/core_concepts) of MeiliSearch. -## Open-source +## Version Compatibility -MeiliSearch is open source. You can **support the project by starring** [our GitHub repository](https://github.com/meilisearch/MeiliSearch)! +This documentation only reflects the latest version of MeiliSearch. We do not provide multi-version documentation. +The current version of [MeiliSearch](https://github.com/meilisearch/MeiliSearch) can be found on the left side of the upper navbar. -Star -Fork +![version of MeiliSearch](/doc-version.png) + +## Same Docs; New Organization + +Hold up a minute—is it just me, or is something different here? 🤔 + +Our documentation has been reorganized to promote **clarity**, **browsability**, and **maintainability**. For starters, our helpful content is now grouped into **three categories**: -## Demo +- [Learn](/learn): If it's your **first-time using MeiliSearch** or you want a refresher, we recommend starting here. -![crates.io demo gif](/crates-io-demo.gif) +- [Create](/create): If you're looking to **start your own MeiliSearch project** or get answers to a question, this is the place. -> Meilisearch helps the Rust community find crates on [crates.meilisearch.com](https://crates.meilisearch.com) +- [Reference](/reference): **Encyclopedia-style documentation** for all of MeiliSearch's [features](/reference/features), [API](/reference/api), and [search engine internals](/reference/under_the_hood). If you just want the facts and none of the fluff, you'll like it here. -## Alternatives +Have fun browsing the new site, and let us know [what you think could be improved](https://github.com/meilisearch/documentation/issues/new). -Why should you use MeiliSearch instead of any other existing solution? We try to answer this question in this [comparison to alternatives](/resources/comparison_to_alternatives.md). In short, Meilisearch most closely compares with Algolia. Meilisearch stands out by being open source (while commercial) and aims to be simpler to deploy and maintain. +Happy searching! 🖖 -## Features +## Open-source + +MeiliSearch is completely open source. You can **support the project by starring** [our GitHub repository](https://github.com/meilisearch/MeiliSearch)! + +Star +Fork -- **Instant Search** (answers < 50 milliseconds): Priority is given to fast answers for smooth search experience. -- **Search as you type** (_prefix search_): Results are updated on each keystroke. To make this possible, we use a [prefix-search](/guides/advanced_guides/prefix.md#prefix-search). -- [Typo tolerance](/guides/advanced_guides/typotolerance.md#typo-tolerance): Understands typo and miss-spelling. -- [Tokenization](/guides/advanced_guides/tokenization.md) in **English**, **Chinese**, and **all languages that uses space as a word divider**. -- **Return the whole document**: The entire document is returned upon search. -- **Highly customizable search and indexation**: - - [Custom ranking](/guides/main_concepts/relevancy.md): Customize the relevancy of the search engine and the ranking of the search results. - - [Stop words](/guides/advanced_guides/stop_words.md): Ignore common non-relevant words like `of` or `the`. - - [Highlights](/guides/advanced_guides/search_parameters.md#attributes-to-highlight): Highlighted search results in documents - - Ability to create [synonyms](/guides/advanced_guides/synonyms.md) for a better search experience. -- **RESTful API** -- **Friendly web interface**: [Integrated web interface](/guides/advanced_guides/web_interface.md) in MeiliSearch that allows to try the search engine out during development. +::: note +This documentation is [completely open-source](https://github.com/meilisearch/documentation). We keep it up-to-date but you might find some typos or mistakes. Help us make it better by submitting a [pull request](https://github.com/meilisearch/documentation/fork) or [issue](https://github.com/meilisearch/documentation/issues) 😁 +::: diff --git a/learn/README.md b/learn/README.md new file mode 100644 index 0000000000..4c128d4c31 --- /dev/null +++ b/learn/README.md @@ -0,0 +1,18 @@ +# Learn MeiliSearch + +Welcome to MeiliSearch's learning center. These resources are aimed at first-time and new users of MeiliSearch. If you're looking for a more detailed or comprehensive resource, have a look at our [reference documentation](/reference). + +## Easy to Learn, Fun to Master + +MeiliSearch has been developed to provide an **easily integrated search solution** with a **simple and intuitive implementation process**. + +It is our fondest hope that anyone could learn the basics simply by looking at our [API endpoints](/reference/api) or [feature references](/reference/features). + +However, if you prefer a more guided or hands-on approach, you're in the right place. We offer helpful descriptions of all of MeiliSearch's [core concepts](/learn/core_concepts), as well as a [beginner-focused tutorial](/learn/tutorials) that should teach you everything you need to start [creating your own projects](/create). + +## Table of Contents + +- [🔎 What Is MeiliSearch](/learn/what_is_meilisearch): Get acquainted with MeiliSearch's features, competitors, SDKs, and more. +- [🚀 Tutorials](/learn/tutorials): Follow a step-by-step tutorial that covers all the basics of MeiliSearch. +- [💡 Core Concepts](/learn/core_concepts): Learn about search fundamentals like documents, indexes, and relevancy. +- [📚 Advanced Topics](/learn/advanced): Deepen your understanding of MeiliSearch with articles about some of our advanced features. diff --git a/learn/advanced/README.md b/learn/advanced/README.md new file mode 100644 index 0000000000..c80583a44b --- /dev/null +++ b/learn/advanced/README.md @@ -0,0 +1,13 @@ +# Advanced Topics + +## Elevate Your Understanding + +Bring your knowledge and understanding of MeiliSearch to the next level with these articles on advanced topics. + +These articles are conceptual explorations of important—but difficult—topics. Unlike our [how-to guides](/create/how_to), they are **not** step-by-step solutions to common problems. + +## Table of Contents + +- [Language](/learn/advanced/language.md) +- [Asynchronous Updates](/learn/advanced/asynchronous_updates.md) +- [Snapshots vs. Dumps](/learn/advanced/snapshots_vs_dumps.md) diff --git a/guides/advanced_guides/asynchronous_updates.md b/learn/advanced/asynchronous_updates.md similarity index 95% rename from guides/advanced_guides/asynchronous_updates.md rename to learn/advanced/asynchronous_updates.md index fba26304de..db790b2bce 100644 --- a/guides/advanced_guides/asynchronous_updates.md +++ b/learn/advanced/asynchronous_updates.md @@ -8,7 +8,7 @@ Some operations are put in a queue and will be executed in turn (asynchronously) - When making a write request (_create/update/delete_) against the search engine, it stores the operation received in a queue and returns an `updateId`. With this id, the operation update is trackable. - Each update received is treated following the order it has been received. -- You can get the update status on the [`/updates`](/references/updates.md) route. +- You can get the update status on the [`/updates`](/reference/api/updates.md) route. - Processed updates are marked as processed and kept in the operation list (available at `/indexes/:index_uid/updates`). They won't be deleted. @@ -84,7 +84,7 @@ Since in MeiliSearch asynchronous tasks are , kil Essentially, tasks are done in transactions. If the transaction fails or is killed for any reason before completing, none of the tasks will be committed to your database. -You can use the `status` field returned by [the update route](/references/updates.md) to determine if a process has been committed to MeiliSearch or not. +You can use the `status` field returned by [the update route](/reference/api/updates.md) to determine if a process has been committed to MeiliSearch or not. - status: `enqueued` => Not yet begun. If MeiliSearch is killed and then restarted, the task will remain enqueued and be processed eventually. - status `processing` => In progress. If MeiliSearch is killed, there will be no consequences, since no part of the task has been committed to MeiliSearch. After restarting, Meilisearch will treat the task as `enqueued`. diff --git a/learn/advanced/language.md b/learn/advanced/language.md new file mode 100644 index 0000000000..255b54799b --- /dev/null +++ b/learn/advanced/language.md @@ -0,0 +1,23 @@ +# Language + +**MeiliSearch is multilingual**, featuring optimized support for: + +- **Any language that uses whitespace to separate words** +- **Chinese** 🇨🇳 (through [Jieba](https://github.com/messense/jieba-rs)) + +We aim to provide global language support, and your feedback helps us [move closer to that goal](#improving-our-language-support). If you notice inconsistencies in your search results or the way your documents are processed, please open an issue on our [GitHub repository](https://github.com/meilisearch/MeiliSearch/issues/new/choose). + +If you'd like to learn more about how different languages are processed in MeiliSearch, see our [tokenizer documentation](/reference/under_the_hood/tokenization.md). + +## Improving Our Language Support + +While we have employees from all over the world at MeiliSearch, we don't speak every language. In fact, we rely almost entirely on feedback from external contributors to know how our engine is performing across different languages. + +If you'd like to help us create a more global MeiliSearch, please consider sharing your tests, results, and general feedback with us through [GitHub issues](https://github.com/meilisearch/MeiliSearch/issues). Here are some of the languages that have been requested by users and their corresponding issue: + +- [Arabic](https://github.com/meilisearch/MeiliSearch/issues/554) +- [Lao](https://github.com/meilisearch/MeiliSearch/issues/563) +- [Persian/Farsi](https://github.com/meilisearch/MeiliSearch/issues/553) +- [Thai](https://github.com/meilisearch/MeiliSearch/issues/864) + +If you'd like us to add or improve support for a language that isn't in the above list, please create an [issue](https://github.com/meilisearch/MeiliSearch/issues/new?assignees=&labels=&template=feature_request.md&title=) saying so, and then make a [pull request on the documentation](https://github.com/meilisearch/documentation/edit/master/guides/advanced_guides/tokenization.md) to add it to the above list. diff --git a/learn/advanced/snapshots_vs_dumps.md b/learn/advanced/snapshots_vs_dumps.md new file mode 100644 index 0000000000..8c6fab0bb7 --- /dev/null +++ b/learn/advanced/snapshots_vs_dumps.md @@ -0,0 +1,27 @@ +# Snapshots vs. Dumps + +MeiliSearch has two ways to backup its data: `snapshots` and `dumps`. + +## Snapshots + +**Snapshots** make it possible to schedule the creation of hard copies of your database. + +This feature is **intended mainly as a safeguard**: ensuring that if some failure occurs, you're able to relaunch your database quickly and efficiently from a snapshot. + +The documents in a snapshot are already "indexed" and ready to go, greatly increasing import speed. However, as a result, **snapshots are not compatible between different versions of MeiliSearch**. + +## Dumps + +**Dumps**, on the other hand, export MeiliSearch data in a way that is not bound to a specific MeiliSearch version. + +As a result, importing a dump requires MeiliSearch to re-index all of your documents. This process requires an amount of time and memory corresponding to the size of the database (the number of documents, their size, and the complexity of any index settings). + +## Conclusion + +To summarize: + +- **Snapshots are highly efficient, but not portable** between different versions of MeiliSearch. +- **Dumps are highly portable, but not very efficient**. + - Frequently launching MeiliSearch from a dump would cause your performance to suffer. + +For more information, have a look at the reference documentation for [snapshots](/reference/features/snapshots.md) and [dumps](/reference/features/dumps.md). diff --git a/learn/core_concepts/README.md b/learn/core_concepts/README.md new file mode 100644 index 0000000000..04a6c99974 --- /dev/null +++ b/learn/core_concepts/README.md @@ -0,0 +1,11 @@ +# Core Concepts + +This section defines the core concepts of MeiliSearch: + +- [Documents](/learn/core_concepts/documents.md): Objects made up of key-value pairs. +- [Indexes](/learn/core_concepts/indexes.md): Entities that contain documents and search-related settings. +- [Relevancy](/learn/core_concepts/relevancy.md): Rules that help you get more intuitive results. The human element of your search engine. + +::: tip Important +MeiliSearch is an **asynchronous** API. This means that, unlike a synchronous API, it doesn't wait for the call to be done as calls are placed in a queue for processing. For further information please read [the advanced guide](/learn/advanced/asynchronous_updates.md). +::: diff --git a/guides/main_concepts/documents.md b/learn/core_concepts/documents.md similarity index 72% rename from guides/main_concepts/documents.md rename to learn/core_concepts/documents.md index 374d2df732..ca0e679fcb 100644 --- a/guides/main_concepts/documents.md +++ b/learn/core_concepts/documents.md @@ -40,11 +40,11 @@ At minimum, the document must contain one field with the **[primary key][primary ### Limitations and Requirements -Documents have a **soft maximum of 1000 fields**; beyond that the [](/guides/main_concepts/relevancy.md#ranking-rules) may no longer be effective, leading to undefined behavior. +Documents have a **soft maximum of 1000 fields**; beyond that the [](/learn/core_concepts/relevancy.md#ranking-rules) may no longer be effective, leading to undefined behavior. Additionally, every document must have at minimum one field containing the **[][primary-key]** and a **[unique id][document-id]**. -If you try to [index a document](/guides/introduction/quick_start_guide.md#add-documents) that's incorrectly formatted, missing a primary key, or possessing the [wrong primary key for a given index](/guides/main_concepts/indexes.md#primary-key), it will cause an error and no documents will be added. +If you try to [index a document](/learn/tutorials/getting_started.md#add-documents) that's incorrectly formatted, missing a primary key, or possessing the [wrong primary key for a given index](/learn/core_concepts/indexes.md#primary-key), it will cause an error and no documents will be added. ## Fields @@ -52,19 +52,19 @@ A is a set of two data items linked together: an An attribute functions a bit like a variable in most programming languages, i.e. it is a name that allows you to store, access, and describe some data. That data is the attribute's **value**. -Every field has a [data type](/guides/advanced_guides/datatypes.md) dictated by its value. Every value must be a valid [`JSON` data type](https://www.w3schools.com/js/js_json_datatypes.asp). +Every field has a [data type](/reference/under_the_hood/datatypes.md) dictated by its value. Every value must be a valid [`JSON` data type](https://www.w3schools.com/js/js_json_datatypes.asp). -Take note that in the case of strings, the value **[can contain at most 1000 words](/guides/advanced_guides/known_limitations.md#maximum-words-per-attribute)**. If it contains more than 1000 words, only the first 1000 will be indexed. +Take note that in the case of strings, the value **[can contain at most 1000 words](/reference/features/known_limitations.md#maximum-words-per-attribute)**. If it contains more than 1000 words, only the first 1000 will be indexed. -You can also apply [](/guides/main_concepts/relevancy.md#ranking-rules) to some fields. For example, you may decide recent movies should be more relevant than older ones. +You can also apply [](/learn/core_concepts/relevancy.md#ranking-rules) to some fields. For example, you may decide recent movies should be more relevant than older ones. -If you would like to adjust how a field gets handled by MeiliSearch, you can do so in the [settings](/guides/advanced_guides/settings.md#settings). +If you would like to adjust how a field gets handled by MeiliSearch, you can do so in the [settings](/reference/features/settings.md#settings). ### Field properties -A field may also possess **[field properties](/guides/advanced_guides/field_properties.md)**. Field properties determine the characteristics and behavior of the data added to that field. +A field may also possess **[field properties](/reference/features/field_properties.md)**. Field properties determine the characteristics and behavior of the data added to that field. -At this time, there are two field properties: [](/guides/advanced_guides/field_properties.md#searchable-fields) and [](/guides/advanced_guides/field_properties.md#displayed-fields). A field can have one, both, or neither of these properties. **By default, all fields in a document are both displayed and searchable.** +At this time, there are two field properties: [](/reference/features/field_properties.md#searchable-fields) and [](/reference/features/field_properties.md#displayed-fields). A field can have one, both, or neither of these properties. **By default, all fields in a document are both displayed and searchable.** To clarify, a field may be: @@ -73,7 +73,7 @@ To clarify, a field may be: - both displayed and searchable (default) - neither displayed nor searchable -In the latter case, the field will be completely ignored when a search is performed. However, it will still be [stored](/guides/advanced_guides/field_properties.md#data-storing) in the document. +In the latter case, the field will be completely ignored when a search is performed. However, it will still be [stored](/reference/features/field_properties.md#data-storing) in the document. ## Primary Field @@ -113,9 +113,9 @@ Each index recognizes **only one** primary key attribute. Once a primary key has There are several ways for MeiliSearch to know which field is the primary key. -- You can set it manually [on index creation](/references/indexes.md#create-an-index) -- You can set it manually [on document addition](/references/documents.md#add-or-replace-documents) -- MeiliSearch can [automatically infer the primary key](/guides/main_concepts/documents.md#meilisearch-infers-your-primary-key) based on your first document. +- You can set it manually [on index creation](/reference/api/indexes.md#create-an-index) +- You can set it manually [on document addition](/reference/api/documents.md#add-or-replace-documents) +- MeiliSearch can [automatically infer the primary key](/learn/core_concepts/documents.md#meilisearch-infers-your-primary-key) based on your first document. #### MeiliSearch infers your primary key @@ -125,7 +125,7 @@ If no corresponding attribute is found, the index will have no known primary key #### Missing primary key error ❗️ If you get the `Could not infer a primary key` error, the primary key was not recognized. This means **your primary key is wrongly formatted or absent**. -Manually adding the primary key can be accomplished by using its name as a parameter for [the add document route](/references/documents.md#add-or-replace-documents) or [the update index route](/references/indexes.md#create-an-index). +Manually adding the primary key can be accomplished by using its name as a parameter for [the add document route](/reference/api/documents.md#add-or-replace-documents) or [the update index route](/reference/api/indexes.md#create-an-index). ### Document Id @@ -155,7 +155,7 @@ Take note that the document addition request in MeiliSearch is -[primary-field]: /guides/main_concepts/documents.md#primary-field -[primary-key]: /guides/main_concepts/documents.md#primary-key -[document-id]: /guides/main_concepts/documents.md#document-id -[fields]: /guides/main_concepts/documents.md#fields -[indexes]: /guides/main_concepts/indexes.md +[primary-field]: /learn/core_concepts/documents.md#primary-field +[primary-key]: /learn/core_concepts/documents.md#primary-key +[document-id]: /learn/core_concepts/documents.md#document-id +[fields]: /learn/core_concepts/documents.md#fields +[indexes]: /learn/core_concepts/indexes.md diff --git a/guides/main_concepts/indexes.md b/learn/core_concepts/indexes.md similarity index 79% rename from guides/main_concepts/indexes.md rename to learn/core_concepts/indexes.md index 3b31013cb4..4396de6327 100644 --- a/guides/main_concepts/indexes.md +++ b/learn/core_concepts/indexes.md @@ -19,11 +19,11 @@ For example, it means you could create on the same server synonyms for a `movie` ## Index Creation -An index is created the first time documents are added to it or manually using the [create index endpoint](/references/indexes.md#create-an-index). +An index is created the first time documents are added to it or manually using the [create index endpoint](/reference/api/indexes.md#create-an-index). #### Example -In a new MeiliSearch instance without any index, let's add documents using the [add or replace documents endpoint](/references/documents.md#add-or-replace-documents). +In a new MeiliSearch instance without any index, let's add documents using the [add or replace documents endpoint](/reference/api/documents.md#add-or-replace-documents). We provide `movies` as our index. Because that index was not previously created, using the following code will: 1. Create the `movie` index. @@ -35,7 +35,7 @@ We provide `movies` as our index. Because that index was not previously created, The `uid` is the **unique** identifier of a given index. It is used on every `indexes/:index_uid` route as the `:index_uid` parameter. -The uid is set at [index creation time](/references/indexes.md#create-an-index). Once a `uid` has been defined for an index, you cannot create another index with the same `uid` and the identifier **cannot be changed anymore**. +The uid is set at [index creation time](/reference/api/indexes.md#create-an-index). Once a `uid` has been defined for an index, you cannot create another index with the same `uid` and the identifier **cannot be changed anymore**. ```json { @@ -49,9 +49,9 @@ The uid is set at [index creation time](/references/indexes.md#create-an-index). An index is a collection of documents. All documents have a primary key, which is a mandatory . This field is composed of a primary key name and a unique value. All documents in a given index share the same primary key attribute but a different unique value. -The primary key's attribute name **must** be known by the index. You can [set a primary key for an index or let it be inferred by MeiliSearch](/guides/main_concepts/documents.md#setting-the-primary-key). +The primary key's attribute name **must** be known by the index. You can [set a primary key for an index or let it be inferred by MeiliSearch](/learn/core_concepts/documents.md#setting-the-primary-key). -[Learn more about document primary key](/guides/main_concepts/documents.md#primary-key) +[Learn more about document primary key](/learn/core_concepts/documents.md#primary-key) ## Relevancy rules @@ -61,7 +61,7 @@ For example, if in your first document attributes are listed as follows: `id, ti On top of that, you can add your custom rules to the ranking rules. For example, you may want to rank your movies either by release date or popularity, or both and so on. **Rules are customizable** so the results meet your user's needs as close as possible. -[Learn more about ranking rules](/guides/main_concepts/relevancy.md) +[Learn more about ranking rules](/learn/core_concepts/relevancy.md) ## Synonyms @@ -69,27 +69,27 @@ In your dataset, you may decide to create synonyms for words which have the same Since synonyms are linked to a given index, they won't apply to any other index on the same MeiliSearch instance. -[Learn more about synonyms](/guides/advanced_guides/synonyms.md) +[Learn more about synonyms](/reference/features/synonyms.md) ## Stop words Sometimes you may want to ignore certain words in documents and search queries. To do so, **a set of stop words can be defined for an index**. Unless you actually need them, some words neither add semantic value nor context. Besides, they are often too frequent (i.e., `the` or `of` in English). -By adding words to a stop words list, these specific terms will be ignored during search. It will avoid documents being considered highly relevant because of the presence of some words in an important [attribute](/guides/main_concepts/relevancy.md#ranking-rules) or in a good [position](/guides/main_concepts/relevancy.md#ranking-rules). This will also greatly improve the response time because all the documents that contain only those words will not be used for documents sorting. +By adding words to a stop words list, these specific terms will be ignored during search. It will avoid documents being considered highly relevant because of the presence of some words in an important [attribute](/learn/core_concepts/relevancy.md#ranking-rules) or in a good [position](/learn/core_concepts/relevancy.md#ranking-rules). This will also greatly improve the response time because all the documents that contain only those words will not be used for documents sorting. For example, suppose you would perform the following search query: `the great gatsby`. Having the word `the` in a film review wouldn't make the review more relevant. By adding `the` to the stop word list, performance would be increased and search results more relevant. -[Learn more about stop words](/guides/advanced_guides/stop_words.md) +[Learn more about stop words](/reference/features/stop_words.md) ## Field properties By default, every document field is searchable and returned on search queries. -Fields can have either or both or none of the following properties that can be modified in the [settings](/references/settings.md): +Fields can have either or both or none of the following properties that can be modified in the [settings](/reference/api/settings.md): - **Searchable**: The content of searchable fields is used by MeiliSearch to assess the relevancy of a document. - **Displayed**: Documents returned upon search contain only displayed fields. By default, each field is stored and this behavior cannot be changed. -[Learn more about field properties](/guides/advanced_guides/field_properties.md) +[Learn more about field properties](/reference/features/field_properties.md) diff --git a/guides/main_concepts/relevancy.md b/learn/core_concepts/relevancy.md similarity index 90% rename from guides/main_concepts/relevancy.md rename to learn/core_concepts/relevancy.md index d3d2af9625..2e6a39501c 100644 --- a/guides/main_concepts/relevancy.md +++ b/learn/core_concepts/relevancy.md @@ -1,6 +1,6 @@ # Relevancy -Search responses are sorted according to a set of consecutive rules called **ranking rules**. When a search query is made, MeiliSearch uses a [bucket sort](/guides/advanced_guides/bucket_sort.md) to rank documents. Each rule is applied to all documents that are considered equal according to the previous rule to break the tie. +Search responses are sorted according to a set of consecutive rules called **ranking rules**. When a search query is made, MeiliSearch uses a [bucket sort](/reference/under_the_hood/bucket_sort.md) to rank documents. Each rule is applied to all documents that are considered equal according to the previous rule to break the tie. Ranking rules are **built-in rules applied to the search results** in order to improve their relevancy. To benefit from the ranking rules and make them meet your dataset and needs, it is important to understand how each of them works and how to create new ones. @@ -32,7 +32,7 @@ It is now mandatory that all query terms are present in the returned documents. Results are sorted by **increasing distance between matched query terms**: find documents that contain more query terms found close together (close proximity between two query terms) and appearing in the original order specified in the query string first. **4. Attribute** -Results are sorted according to the **[attribute ranking order](/guides/main_concepts/relevancy.md#attribute-ranking-order)**: find documents that contain query terms in more important attributes first. +Results are sorted according to the **[attribute ranking order](/learn/core_concepts/relevancy.md#attribute-ranking-order)**: find documents that contain query terms in more important attributes first. **5. Words Position** Results are sorted by **the position of the query words in the attributes**: find documents that contain query terms earlier in their attributes first. @@ -75,7 +75,7 @@ The `proximity` rule sorts the results by increasing distance between matched qu `If It's Tuesday, This must be Belgium` is the first document because the matched word `Belgium`, is found in the `title` attribute and not the `description`. -The `attribute` rule sorts the results by [attribute importance](/guides/main_concepts/relevancy.md#attribute-ranking-order). +The `attribute` rule sorts the results by [attribute importance](/learn/core_concepts/relevancy.md#attribute-ranking-order). ::: @@ -110,7 +110,7 @@ By default, the built-in rules are executed in the following order to meet most ["typo", "words", "proximity", "attribute", "wordsPosition", "exactness"] ``` -Depending on your needs, you might want to change this order of importance. To do so, you can use the [settings route](/references/ranking_rules.md#update-ranking-rules) of your index. +Depending on your needs, you might want to change this order of importance. To do so, you can use the [settings route](/reference/api/ranking_rules.md#update-ranking-rules) of your index. ## Adding your rules @@ -124,7 +124,7 @@ To add your own ranking rule, you have to communicate either `asc` for ascending - To apply a **descending sorting** (results sorted by decreasing value of the attribute): `desc(attribute_name)` -Add this rule to the existing list of ranking rules using the [settings route](/references/ranking_rules.md#update-ranking-rules). +Add this rule to the existing list of ranking rules using the [settings route](/reference/api/ranking_rules.md#update-ranking-rules). #### Example @@ -142,7 +142,7 @@ The following example will create a rule that makes movies with a good rank more desc(movie_ranking) ``` -To add a rule to the existing ranking rule, you have to add the rule to the existing ordered rules array using the [settings route](/references/ranking_rules.md#update-ranking-rules), +To add a rule to the existing ranking rule, you have to add the rule to the existing ordered rules array using the [settings route](/reference/api/ranking_rules.md#update-ranking-rules), ```json [ @@ -163,7 +163,7 @@ In a typical dataset, some fields are more relevant to search than others. A `ti By default, the attribute ranking order is generated automatically based on the attributes' order of appearance in the indexed documents. However, it can also be set manually. -For a more detailed look at this subject, see our reference page for [the searchable attributes list](/guides/advanced_guides/field_properties.md#the-searchable-attributes-list). +For a more detailed look at this subject, see our reference page for [the searchable attributes list](/reference/features/field_properties.md#the-searchable-attributes-list). #### Example diff --git a/learn/tutorials/README.md b/learn/tutorials/README.md new file mode 100644 index 0000000000..c4068ccc89 --- /dev/null +++ b/learn/tutorials/README.md @@ -0,0 +1,14 @@ +# Learn MeiliSearch Through Tutorials + +The aim of these tutorials is **to provide a thorough introduction to all of MeiliSearch's core features** and prepare you to start your own MeiliSearch projects. + +It is **not** to provide exhaustive or universal instructions on how to use MeiliSearch's [SDKs](/learn/what_is_meilisearch/sdks.md) or [API](/reference/api). + +## Table of Contents: + +- 🚀 [Getting Started](/learn/tutorials/getting_started.md) + - [Download and launch MeiliSearch](/learn/tutorials/getting_started.md#download-and-launch) + - [Add documents](/learn/tutorials/getting_started.md#add-documents) + - [Search!](/learn/tutorials/getting_started.md#search) + - [Integrate with Your Project](/learn/tutorials/getting_started.md#integrate-with-your-project) +- 👩‍🚀 [What's next?](/learn/tutorials/whats_next.md) diff --git a/guides/introduction/quick_start_guide.md b/learn/tutorials/getting_started.md similarity index 87% rename from guides/introduction/quick_start_guide.md rename to learn/tutorials/getting_started.md index 86bd64302a..17842e1baf 100644 --- a/guides/introduction/quick_start_guide.md +++ b/learn/tutorials/getting_started.md @@ -12,26 +12,26 @@ $ ./meilisearch Server is listening on: http://127.0.0.1:7700 ``` -You can download & run MeiliSearch [in many different ways (i.e: docker, apt, homebrew, ...)](/guides/advanced_guides/installation.md). +You can download & run MeiliSearch [in many different ways (i.e: docker, apt, homebrew, ...)](/reference/features/installation.md). -[Environment variables and options](/guides/advanced_guides/configuration.md) can be set before and on launch to configure MeiliSearch. Amongst all the options, you can use the **master key** and the **port** options. +[Environment variables and options](/reference/features/configuration.md) can be set before and on launch to configure MeiliSearch. Amongst all the options, you can use the **master key** and the **port** options. ### Communicate with MeiliSearch Now that your MeiliSearch server is up and running, you should be able to communicate with it. -Communication to the server is done through a [RESTful API](/references/README.md) or one of our [SDKs](/resources/sdks.md). +Communication to the server is done through a [RESTful API](/reference/api/README.md) or one of our [SDKs](/learn/what_is_meilisearch/sdks.md). ## Add Documents To add documents to MeiliSearch you must provide: -- [Documents](/guides/main_concepts/documents.md) in the form of `JSON objects`. -- An [index](/guides/main_concepts/indexes.md) name (_uid_). An index is where the documents are stored. +- [Documents](/learn/core_concepts/documents.md) in the form of `JSON objects`. +- An [index](/learn/core_concepts/indexes.md) name (_uid_). An index is where the documents are stored. > _If the index does not exist, MeiliSearch creates it when you first add documents._ -To be processed, all documents must share one common which will serve as [](/guides/main_concepts/documents.md#primary-key) for the document. Values in that field must always be **unique**. +To be processed, all documents must share one common which will serve as [](/learn/core_concepts/documents.md#primary-key) for the document. Values in that field must always be **unique**. ```json { @@ -42,13 +42,13 @@ To be processed, all documents must share one common that contains the string `id` in a case-insensitive manner. +There are [several ways to let MeiliSearch know what the primary key](/learn/core_concepts/documents.md#primary-key) is. The easiest one is to have an that contains the string `id` in a case-insensitive manner. Below is an example to showcase how to add documents to an index called `movies` using the following test dataset: [movies.json](https://github.com/meilisearch/MeiliSearch/blob/master/datasets/movies/movies.json). -[API references](/references/documents.md) +[API references](/reference/api/documents.md) ### Checking updates @@ -58,17 +58,17 @@ The document addition process returns a JSON object containing only an `updateId This kind of **successful response** indicates that the operation has been taken into account, but may not have been executed yet. -You can check the status of the operation via the `updateId` and the [get update status route](/references/updates.md). +You can check the status of the operation via the `updateId` and the [get update status route](/reference/api/updates.md). Checking the update status is not a mandatory step to search through your documents but could prove useful in tracing the origin of errors or unexpected behaviors. -[API references](/references/updates.md) +[API references](/reference/api/updates.md) ## Search -Now that your documents have been ingested into MeiliSearch, you are able to [search them](/guides/main_concepts/search.md). +Now that your documents have been ingested into MeiliSearch, you are able to search them. -MeiliSearch [offers many parameters](/guides/advanced_guides/search_parameters.md) that you can play with to refine your search or change the format of the returned documents. However, by default, the search is already relevant. +MeiliSearch [offers many parameters](/reference/features/search_parameters.md) that you can play with to refine your search or change the format of the returned documents. However, by default, the search is already relevant. The search engine is now aware of your documents and can serve those via an HTTP server. @@ -102,11 +102,11 @@ MeiliSearch **response**: } ``` -[API references](/references/search.md) +[API references](/reference/api/search.md) ### Web Interface -We also deliver an out-of-the-box [web interface](/guides/advanced_guides/web_interface.md) in which you can test MeiliSearch interactively. +We also deliver an out-of-the-box [web interface](/reference/features/web_interface.md) in which you can test MeiliSearch interactively. To do so, open your web browser and enter MeiliSearch address (in our case: `http://127.0.0.1:7700`) into the browser address bar. This will lead you to a web page with a search bar that will allow you to search in the selected index. @@ -115,7 +115,7 @@ This will lead you to a web page with a search bar that will allow you to search
-## Integrate to Your Project +## Integrate with Your Project The only step missing now is adding the search bar to your project. The easiest way of achieving this is to use [instant-meilisearch](https://github.com/meilisearch/instant-meilisearch): a developer tool that generates all the search components needed to start searching. @@ -301,4 +301,4 @@ To use `instant-meilisearch` in `React` using `npm` or `yarn` please visit [meil :::: -You should now have a MeiliSearch database and a working front-end search interface 🚀🔥 Check out [What’s Next](/guides/introduction/whats_next.md) to continue your MeiliSearch journey. +You should now have a MeiliSearch database and a working front-end search interface 🚀🔥 Check out [What’s Next](/learn/tutorials/whats_next.md) to continue your MeiliSearch journey. diff --git a/learn/tutorials/whats_next.md b/learn/tutorials/whats_next.md new file mode 100644 index 0000000000..4ec47a08c1 --- /dev/null +++ b/learn/tutorials/whats_next.md @@ -0,0 +1,21 @@ +# What's next? + +MeiliSearch was built on a few core concepts. If you haven't already done so, we invite you to explore the following pages that will give you an essential insight into our search engine: + +- [Documents](/learn/core_concepts/documents.md) +- [Indexes](/learn/core_concepts/indexes.md) +- [Relevancy](/learn/core_concepts/relevancy.md) + +You can find the API references here: + +- [API References](/reference/api/README.md) + +And additional resources here: + +- [SDKs](/learn/what_is_meilisearch/sdks.md) +- [FAQ](/create/faq.md) +- [Advanced Topics](/learn/advanced) +- [How-To Guides](/create/how_to) +- [Postman Collection](/create/how_to/postman_collection.md): it can be tedious to re-write every route when wanting to try out an API. Try out MeiliSearch with our collection in Postman + +More tutorials are currently in development and will be available soon. diff --git a/learn/what_is_meilisearch/README.md b/learn/what_is_meilisearch/README.md new file mode 100644 index 0000000000..4bfc544512 --- /dev/null +++ b/learn/what_is_meilisearch/README.md @@ -0,0 +1,54 @@ +# What Is MeiliSearch? + +MeiliSearch is a **RESTful search API**. It aims to be a **ready-to-go solution** for everyone who wants a **fast and relevant search experience** for their end-users ⚡️🔎 + +Efficient search engines often require a significant investment of resources. They are only accessible to companies with the means necessary to develop a bespoke search solution that fits their needs. + +Small-to-medium-sized businesses commonly resort to subpar search engines that incur invisible costs on their user experience and retention due to poor search fulfillment. + +That's why we created MeiliSearch: An open source solution accessible to everyone, designed to meet a vast majority of needs. Requiring very little configuration to be installed, yet highly customizable. + +Our solution delivers an **instant search experience** including **typo handling**, **filters**, **custom rankings**, and many more [features](#features). Read on to learn more. + +## Demo + +![crates.io demo gif](/crates-io-demo.gif) + +> Meilisearch helps the Rust community find crates on [crates.meilisearch.com](https://crates.meilisearch.com) + +## Features + +- **Blazing fast** (answers < 50 milliseconds): Priority is given to fast answers for a smooth search experience. +- [Search as you type](/learn/what_is_meilisearch/features.md#search-as-you-type): Results are updated on each keystroke. To make this possible, we use [prefix-search](/reference/under_the_hood/prefix.md#prefix-search). +- [Typo tolerance](/learn/what_is_meilisearch/features.md#typo-tolerance): Understands typoes and misspellings. +- [Tokenization](/reference/under_the_hood/tokenization.md) in **English**, **Chinese**, and **all languages that uses space as a word divider**. +- **Return the whole document**: The entire document is returned upon search. +- **Highly customizable search and indexation**: + - [Custom ranking](/learn/core_concepts/relevancy.md): Customize the relevancy of the search engine and the ranking of the search results. + - [Stop words](/reference/features/stop_words.md): Ignore common non-relevant words like `of` or `the`. + - [Highlighting](/learn/what_is_meilisearch/features.md#highlighting): Highlighted search results in documents + - [Synonyms](/learn/what_is_meilisearch/features.md#synonyms): define synonyms for a better search experience. +- **RESTful API** +- [Integrated web interface](/reference/features/web_interface.md): allows you to test your search settings without implementing a front-end + +## Philosophy + +MeiliSearch is committed to providing **open source**, **easy to use**, **customizable** instant search that **focuses on the needs of end-users**. + +Read more about [the philosophy of our search engine](/learn/what_is_meilisearch/philosophy.md). + +## SDKs and Integrations + +Our team and community have worked hard to bring MeiliSearch to almost all popular web development languages, frameworks, and deployment options—and new integrations are constantly in development. Check out [the full list of our integrations](/learn/what_is_meilisearch/sdks.md). + +## Alternatives + +Why should you use MeiliSearch instead of any other existing solution? We try to answer this question in this [comparison to alternatives](/learn/what_is_meilisearch/comparison_to_alternatives.md). In short, MeiliSearch most closely compares with Algolia. MeiliSearch stands out by being open source (while commercial), and aims to be simpler to deploy and maintain than other competitors. + +## Give it a try! + +Instead of showing you examples, why not just invite you to test MeiliSearch interactively in the **out-of-the-box web interface** we deliver? + +There's no need to write a single line of front-end code. All you need to do is follow [this guide](/reference/features/web_interface.md) to give the search engine a try! + +![web interface](/web-interface.png) diff --git a/resources/comparison_to_alternatives.md b/learn/what_is_meilisearch/comparison_to_alternatives.md similarity index 100% rename from resources/comparison_to_alternatives.md rename to learn/what_is_meilisearch/comparison_to_alternatives.md diff --git a/resources/contact.md b/learn/what_is_meilisearch/contact.md similarity index 72% rename from resources/contact.md rename to learn/what_is_meilisearch/contact.md index 10428b2227..a0ca282314 100644 --- a/resources/contact.md +++ b/learn/what_is_meilisearch/contact.md @@ -10,13 +10,11 @@ Your project announcements, feature proposals, support queries and sweet, sweet Prefer the speed and fluidity of chat? Then join our [Slack community](https://slack.meilisearch.com/). -You can also talk to us via the bottom right chat widget available on every page of [our documentation](https://docs.meilisearch.com/) and on [our landing page](https://www.meilisearch.com/). - We think chat and forum discussions are [highly complementary](https://blog.discourse.org/2018/04/effectively-using-discourse-together-with-group-chat/), happily co-existing as two different modes of conversation. Try use the right tool for the job; but most importantly we just want to hear from you, regardless of medium! ## GitHub Issues 🔩 -Pull requests or bug reports should be added to the Issues of its respective repository, e.g. [meilisearch/MeiliSearch](https://github.com/meilisearch/MeiliSearch/issues), [meilisearch/documentation](https://github.com/meilisearch/documentation/issues) and so forth. +Bug reports should be added as issues in the corresponding repository, e.g. [meilisearch/MeiliSearch](https://github.com/meilisearch/MeiliSearch/issues), [meilisearch/documentation](https://github.com/meilisearch/documentation/issues) and so forth. ## Email 💌 diff --git a/learn/what_is_meilisearch/features.md b/learn/what_is_meilisearch/features.md new file mode 100644 index 0000000000..4c610777a6 --- /dev/null +++ b/learn/what_is_meilisearch/features.md @@ -0,0 +1,39 @@ +# Features + +All of MeiliSearch's features are provided right out of the box, and can be easily [configured](/reference/features/search_parameters.md). Here are a few of them that you should try out! + +## Search-as-you-type + +Also called "instant search". Results are delivered while you're still inputting your query. Displayed results are changed in real-time whenever you type additional text into the search box. + +## Typo Tolerance + +Instead of letting typos ruin your search experience, MeiliSearch will always find the results you expect. +Read more about typo tolerance in [this dedicated guide](/reference/under_the_hood/typotolerance.md). + +## Synonyms + +![search demo gif](/search-synonyms-typo.gif) + +> MeiliSearch in action with `batman` and `joker` defined as synonyms. + +Defining synonyms lets you craft a more tailored, intuitive search experience. +Read more about synonyms in [this dedicated guide](/reference/features/synonyms.md). + +## Highlighting + +[Highlight](/reference/features/search_parameters.md#attributes-to-highlight) query terms so that matches pop out to the eye. Users don't need to read the entire text to find the match. + +## Filters + +Meilisearch allows you to define [filters](/reference/features/filtering.md) so you can filter through the results based on criteria. + +## Faceting + +[Faceted search](/reference/features/faceted_search.md) allows you to classify search results into categories and to build intuitive navigation interfaces. + +## Placeholder Search + +If you make a search without inputting any query words, MeiliSearch will return all the documents in that index sorted by its [custom ranking rules](/reference/features/settings.md#custom-ranking-rule). This feature is called **placeholder search**. It is particularly effective when used with other features such as [faceting or filtering](/reference/features/faceted_search.md#filters-or-facets), which allow users to narrow their searches and browse by category. + +Placeholder search is not affected by MeiliSearch's [default ranking rules](/reference/features/settings.md#ranking-rules)—only custom rules added by a user. If no custom rules have been set, the results are displayed in the order of their internal database position. diff --git a/learn/what_is_meilisearch/philosophy.md b/learn/what_is_meilisearch/philosophy.md new file mode 100644 index 0000000000..ebecb4dacf --- /dev/null +++ b/learn/what_is_meilisearch/philosophy.md @@ -0,0 +1,35 @@ +# Philosophy + +Finding a high-quality search engine can be difficult. We decided to create MeiliSearch because we noticed that no search engine on the market was powerful, simple, and accessible to individuals and small companies. **Ease of use** was our primary goal starting out, and continues to drive the development of MeiliSearch today. + +## Simple and Intuitive + +We always aim for a simple and intuitive experience for both developers and end-users. + +For developers, we're proud to say that MeiliSearch requires very little configuration to get up and running. Communication to the server is done through a [RESTful API](/reference/api). + +For end-users, the search experience aims to feel simple so they can focus on the results. MeiliSearch aims to deliver an intuitive search-as-you-type experience, with a response time lower than 50 milliseconds. + +## Highly Customizable + +MeiliSearch works out-of-the-box with default settings that meet the needs of most projects. However, searching is still highly customizable. + +> It wouldn't be a search engine if there wasn't a notion of relevancy in the results returned. + +The returned results are **sorted according to a set of consecutive rules called [ranking rules](/learn/core_concepts/relevancy.md#ranking-rules)**. You can delete existing rules, add new ones, or even change the order in which they are executed. + +You can also **configure the [search parameters](/reference/features/search_parameters.md)** to refine your search even further. We support [filters](/reference/features/filtering.md) and [faceting](/reference/features/faceted_search.md). + +## Front-Facing Search + +MeiliSearch aims to be your go-to search backend when you want to build a great search experience for your end-users. + +It's not designed for searching through large data collections (> 10M documents) or industrial applications. + +As a result, we are fully committed to the philosophy of [prefix search](https://en.wikipedia.org/wiki/Trie). + +## Anti-pattern + +MeiliSearch should **not be your main data store**. MeiliSearch should contain only the data you want your users to search through. The more data MeiliSearch contains, the less relevant it is. + +MeiliSearch queries should be sent directly from the front-end. The more proxy there is between MeiliSearch and the end-user, the less fast queries and thus search-experience will be. diff --git a/resources/sdks.md b/learn/what_is_meilisearch/sdks.md similarity index 82% rename from resources/sdks.md rename to learn/what_is_meilisearch/sdks.md index 2e3a970e15..e2d5cc05eb 100644 --- a/resources/sdks.md +++ b/learn/what_is_meilisearch/sdks.md @@ -1,5 +1,9 @@ # Official SDKs / Libraries +Our team and community have worked hard to bring MeiliSearch to almost all popular web development languages, frameworks, and deployment options. + +New integrations are constantly in development. If you'd like to contribute, [see below](/learn/what_is_meilisearch/sdks.md#contributing). + ## SDKs You can use MeiliSearch API wrappers in your favorite language. These libraries support all API routes. @@ -28,7 +32,7 @@ You can use MeiliSearch API wrappers in your favorite language. These libraries ## DevOps Tools -- [meilisearch-digitalocean](https://github.com/meilisearch/meilisearch-digitalocean): how to deploy a MeiliSearch instance on DigitalOcean. See this [dedicated page](/resources/howtos/digitalocean_droplet.md) to use it. +- [meilisearch-digitalocean](https://github.com/meilisearch/meilisearch-digitalocean): how to deploy a MeiliSearch instance on DigitalOcean. See this [dedicated page](/create/how_to/digitalocean_droplet.md) to use it. - [meilisearch-kubernetes](https://github.com/meilisearch/meilisearch-kubernetes): how to deploy a MeiliSearch instance on Kubernetes. ## Other Tools @@ -43,4 +47,4 @@ We are proud that some of our libraries were developed and are still maintained We recommend to follow [these guidelines](https://github.com/meilisearch/integrations-guides) so that it will be easier to integrate your work. -Feel free to [contact us](https://docs.meilisearch.com/faq/#how-can-i-contact-the-meilisearch-team)! 🙂 +Feel free to [contact us](/learn/what_is_meilisearch/contact.md)! 🙂 diff --git a/reference/README.md b/reference/README.md new file mode 100644 index 0000000000..aaeed408f8 --- /dev/null +++ b/reference/README.md @@ -0,0 +1,11 @@ +# Reference + +Welcome to MeiliSearch's reference documentation. Here you will find straightforward, factual descriptions of **features**, **API routes**, and **the algorithms behind the engine**. + +This is **timeless knowledge**. We recommend keeping it open in a spare tab, whether working on your first, tenth, or thousandth MeiliSearch project. + +## Table of Contents + +- [⭐ Features](/reference/features) +- [📒 API](/reference/api) +- [🛠️ Under the Hood](/reference/under_the_hood) diff --git a/references/README.md b/reference/api/README.md similarity index 62% rename from references/README.md rename to reference/api/README.md index 006c9f42c9..9ba017da33 100644 --- a/references/README.md +++ b/reference/api/README.md @@ -1,34 +1,27 @@ -# API References +# API Reference Welcome to the MeiliSearch API documentation. ::: tip -Check out [the FAQ](/faq/) for answers to some common questions 💡 +Check out [the FAQ](/create/faq.md) for answers to some common questions 💡 ::: -## Version Compatibility - -This documentation only reflects the latest version of MeiliSearch. We do not provide multi-version documentation. -The current version of [MeiliSearch](https://github.com/meilisearch/MeiliSearch) can be found on the left side of the upper navbar. - -![version of MeiliSearch](/doc-version.png) - ## Headers ### Recommended Headers #### Content Type -All request and response body are in `JSON`. +Every request and response body is in `JSON`. It is **not required** to have `Content-Type: application/json` in the header. Any content-type is accepted. #### Authentication For almost all routes, you need to be recognized by the server to check your permissions. Add your API key to your headers. -Please read the [advanced part about keys](/guides/advanced_guides/authentication.md) and [how to manage them](/references/keys.md) for more information. +Please read about [authentication keys](/reference/features/authentication.md) and [how to manage them](/reference/api/keys.md) for more information. `X-Meili-API-Key: $API_KEY` @@ -76,7 +69,7 @@ MeiliSearch is an **asynchronous API**. It means that, in a lot of cases, you wi } ``` -This kind of successful response indicates that the operation has been taken into account, but it may not have been executed yet. -You can check the status of the operation via the `updateId` and the [get update status route](/references/updates.md). +This successful response indicates that the operation has been queued or is currently executing. +You can check the status of the operation via the `updateId` and the [get update status route](/reference/api/updates.md). -See more information about [asynchronous updates](/guides/advanced_guides/asynchronous_updates.md). +See more information about [asynchronous updates](/learn/advanced/asynchronous_updates.md). diff --git a/references/attributes_for_faceting.md b/reference/api/attributes_for_faceting.md similarity index 69% rename from references/attributes_for_faceting.md rename to reference/api/attributes_for_faceting.md index 29b2388696..925f23ec96 100644 --- a/references/attributes_for_faceting.md +++ b/reference/api/attributes_for_faceting.md @@ -1,18 +1,18 @@ # Attributes for Faceting -_Child route of the [settings route](/references/settings.md)._ +_Child route of the [settings route](/reference/api/settings.md)._ -The attributes that can be used as [facets for faceted search](/guides/advanced_guides/faceted_search.md). +The attributes that can be used as [facets for faceted search](/reference/features/faceted_search.md). -Attributes for faceting can also be updated directly through the [global settings route](/references/settings.md#update-settings) along with the other settings. +Attributes for faceting can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. -[Learn more about faceted search](/guides/advanced_guides/faceted_search.md). +[Learn more about faceted search](/reference/features/faceted_search.md). ## Get Attributes for Faceting -Get the [attributes for faceting](/guides/advanced_guides/faceted_search.md) of an index. +Get the [attributes for faceting](/reference/features/faceted_search.md) of an index. #### Path Variables @@ -36,7 +36,7 @@ List the settings. -Update the [attributes for faceting](/guides/advanced_guides/faceted_search.md) of an index. +Update the [attributes for faceting](/reference/features/faceted_search.md) of an index. #### Path Variables @@ -48,7 +48,7 @@ Update the [attributes for faceting](/guides/advanced_guides/faceted_search.md) An array of strings that contains the attributes to use as facets. -[More information about the body](/guides/advanced_guides/settings.md#attributes-for-faceting). +[More information about the body](/reference/features/settings.md#attributes-for-faceting). ### Example @@ -62,13 +62,13 @@ An array of strings that contains the attributes to use as facets. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Reset Attributes for Faceting -Reset the [attributes for faceting](/guides/advanced_guides/faceted_search.md) of the index to the default value. +Reset the [attributes for faceting](/reference/features/faceted_search.md) of the index to the default value. #### Default value @@ -92,4 +92,4 @@ An empty array (`[]`). } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/displayed_attributes.md b/reference/api/displayed_attributes.md similarity index 74% rename from references/displayed_attributes.md rename to reference/api/displayed_attributes.md index 7589edd86f..d61f7da963 100644 --- a/references/displayed_attributes.md +++ b/reference/api/displayed_attributes.md @@ -1,23 +1,23 @@ # Displayed attributes -_Child route of the [settings route](/references/settings.md)._ +_Child route of the [settings route](/reference/api/settings.md)._ The fields whose attributes are added to the displayed-attributes list are **displayed in each matching document**. By default, all fields are considered to be `displayedAttributes`. This behavior is represented by the `*` in the settings. Setting `displayedAttributes` to an empty array `[]` will reset the setting to its default value. -Displayed attributes can also be updated directly through the [global settings route](/references/settings.md#update-settings) along with the other settings. +Displayed attributes can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. ::: note Updating the settings means overwriting the default settings of MeiliSearch. You can reset to default values using the `DELETE` routes. ::: -[Learn more about displayed fields](/guides/advanced_guides/field_properties.md#displayed-fields). +[Learn more about displayed fields](/reference/features/field_properties.md#displayed-fields). ## Get displayed attributes -Get the [displayed attributes](/guides/advanced_guides/settings.md#displayed-attributes) of an index. +Get the [displayed attributes](/reference/features/settings.md#displayed-attributes) of an index. #### Path Variables @@ -41,7 +41,7 @@ List the settings. -Update the [displayed attributes](/guides/advanced_guides/settings.md#displayed-attributes) of an index. +Update the [displayed attributes](/reference/features/settings.md#displayed-attributes) of an index. #### Path Variables @@ -53,7 +53,7 @@ Update the [displayed attributes](/guides/advanced_guides/settings.md#displayed- An array of strings that contains attributes of an index to display. -[More information about the body](/guides/advanced_guides/settings.md#displayed-attributes). +[More information about the body](/reference/features/settings.md#displayed-attributes). #### Example @@ -67,13 +67,13 @@ An array of strings that contains attributes of an index to display. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Reset displayed attributes -Reset the [displayed attributes](/guides/advanced_guides/settings.md#displayed-attributes) of the index to the default value. +Reset the [displayed attributes](/reference/features/settings.md#displayed-attributes) of the index to the default value. #### Default value @@ -97,4 +97,4 @@ All attributes found in the documents added to the index. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/distinct_attribute.md b/reference/api/distinct_attribute.md similarity index 65% rename from references/distinct_attribute.md rename to reference/api/distinct_attribute.md index 6a48aa05c6..3a03bb321e 100644 --- a/references/distinct_attribute.md +++ b/reference/api/distinct_attribute.md @@ -1,22 +1,22 @@ # Distinct attribute -_Child route of the [settings route](/references/settings.md)._ +_Child route of the [settings route](/reference/api/settings.md)._ -[Distinct attribute](/guides/advanced_guides/distinct.md) is a field whose value will always be **unique** in the returned documents. +[Distinct attribute](/reference/features/distinct.md) is a field whose value will always be **unique** in the returned documents. -Distinct attribute can also be updated directly through the [global settings route](/references/settings.md#update-settings) along with the other settings. +Distinct attribute can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. ::: note Updating the settings means overwriting the default settings of MeiliSearch. You can reset to default values using the `DELETE` routes. ::: -[Learn more about distinct attribute](/guides/advanced_guides/settings.md#distinct-attribute). +[Learn more about distinct attribute](/reference/features/settings.md#distinct-attribute). ## Get distinct attribute -Get the [distinct attribute](/guides/advanced_guides/settings.md#distinct-attribute) field of an index. +Get the [distinct attribute](/reference/features/settings.md#distinct-attribute) field of an index. #### Path Variables @@ -38,7 +38,7 @@ Get the [distinct attribute](/guides/advanced_guides/settings.md#distinct-attrib -Update the [distinct attribute](/guides/advanced_guides/settings.md#distinct-attribute) field of an index. +Update the [distinct attribute](/reference/features/settings.md#distinct-attribute) field of an index. #### Path Variables @@ -50,7 +50,7 @@ Update the [distinct attribute](/guides/advanced_guides/settings.md#distinct-att A String: the field name. -[More information about the body](/guides/advanced_guides/settings.md#distinct-attribute). +[More information about the body](/reference/features/settings.md#distinct-attribute). ### Example @@ -64,13 +64,13 @@ A String: the field name. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Reset distinct attribute -Reset the [distinct attribute](/guides/advanced_guides/settings.md#distinct-attribute) field of an index to its default value. +Reset the [distinct attribute](/reference/features/settings.md#distinct-attribute) field of an index to its default value. **Default value**: `null` @@ -92,4 +92,4 @@ Reset the [distinct attribute](/guides/advanced_guides/settings.md#distinct-attr } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/documents.md b/reference/api/documents.md similarity index 81% rename from references/documents.md rename to reference/api/documents.md index d8529d7af2..c53fb543a9 100644 --- a/references/documents.md +++ b/reference/api/documents.md @@ -3,21 +3,21 @@ Documents are objects composed of fields that can store any type of data. Each field contains an attribute and its associated value. -Documents are stored inside [indexes](/guides/main_concepts/indexes.md). -[Learn more about documents](/guides/main_concepts/documents.md). +Documents are stored inside [indexes](/learn/core_concepts/indexes.md). +[Learn more about documents](/learn/core_concepts/documents.md). ## Get one document -Get one [document](/guides/main_concepts/documents.md) using its unique id. +Get one [document](/learn/core_concepts/documents.md) using its unique id. #### Path Variables | Variable | Description | | --------------- | ----------------------------------------------------------------- | | **index_uid** | The index UID | -| **document_id** | [The document id](/guides/main_concepts/documents.md#primary-key) | +| **document_id** | [The document id](/learn/core_concepts/documents.md#primary-key) | ### Example @@ -39,7 +39,7 @@ Get one [document](/guides/main_concepts/documents.md) using its unique id. -Get [documents](/guides/main_concepts/documents.md) by batch. +Get [documents](/learn/core_concepts/documents.md) by batch. Using the query parameters `offset` and `limit`, you can browse through all your documents. @@ -90,11 +90,11 @@ Documents are ordered by MeiliSearch depending on the hash of their id. -Add a list of [documents](/guides/main_concepts/documents.md) or replace them if they already exist. If the provided index does not exist, it will be created. +Add a list of [documents](/learn/core_concepts/documents.md) or replace them if they already exist. If the provided index does not exist, it will be created. -If you send an already existing document (same [id](/guides/main_concepts/documents.md#primary-key)) the **whole existing document** will be overwritten by the new document. Fields previously in the document not present in the new document are removed. +If you send an already existing document (same [id](/learn/core_concepts/documents.md#primary-key)) the **whole existing document** will be overwritten by the new document. Fields previously in the document not present in the new document are removed. -For a partial update of the document see [add or update documents](/references/documents.md#add-or-update-documents). +For a partial update of the document see [add or update documents](/reference/api/documents.md#add-or-update-documents). If the provided index does not exist, it will be created. @@ -108,7 +108,7 @@ If the provided index does not exist, it will be created. | Query Parameter | Description | Default Value | | --------------- | ----------------------------------------------------------------------------------------------- | :-----------: | -| **primaryKey** | The [primary key](/guides/main_concepts/documents.md#primary-key) of the documents _(optional)_ | none | +| **primaryKey** | The [primary key](/learn/core_concepts/documents.md#primary-key) of the documents _(optional)_ | none | If you want to set the **primary key** of your index through this route, it only has to be done **the first time you add documents** to the index. After which it will be ignored if given. @@ -140,7 +140,7 @@ The body is composed of a **JSON array** of documents. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Add or update documents @@ -148,9 +148,9 @@ This `updateId` allows you to [track the current update](/references/updates.md) Add a list of documents or update them if they already exist. If the provided index does not exist, it will be created. -If you send an already existing document (same [id](/guides/main_concepts/documents.md#primary-key)) the old document will be only partially updated according to the fields of the new document. Thus, any fields not present in the new document are kept and remained unchanged. +If you send an already existing document (same [id](/learn/core_concepts/documents.md#primary-key)) the old document will be only partially updated according to the fields of the new document. Thus, any fields not present in the new document are kept and remained unchanged. -To completely overwrite a document, check out the [add or replace documents route](/references/documents.md#add-or-replace-documents). +To completely overwrite a document, check out the [add or replace documents route](/reference/api/documents.md#add-or-replace-documents). If the provided index does not exist, it will be created. @@ -166,7 +166,7 @@ If you want to set the **primary key** of your index through this route, it only | Query Parameter | Description | Default Value | | --------------- | ----------------------------------------------------------------------------------------------- | :-----------: | -| **primaryKey** | The [primary key](/guides/main_concepts/documents.md#primary-key) of the documents _(optional)_ | none | +| **primaryKey** | The [primary key](/learn/core_concepts/documents.md#primary-key) of the documents _(optional)_ | none | #### Body @@ -184,7 +184,7 @@ The body is composed of a **JSON array** of documents. ### Example -This document is an update of the document found in [add or replace document](/references/documents.md#add-or-replace-documents). +This document is an update of the document found in [add or replace document](/reference/api/documents.md#add-or-replace-documents). The documents are matched because they have the same `primaryKey` value `id: 287947`. This route will update the `title` field as it changed from `Shazam` to `Shazam ⚡️` and add the new `genres` field to that document. The rest of the document will remain unchanged. #### Response: `202 Accepted` @@ -195,7 +195,7 @@ The documents are matched because they have the same `primaryKey` value `id: 287 } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Delete all documents @@ -221,7 +221,7 @@ Delete all documents in the specified index. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Delete one document @@ -234,7 +234,7 @@ Delete one document based on its unique id. | Variable | Description | | --------------- | ----------------------------------------------------------------- | | **index_uid** | The index UID | -| **document_id** | [The document id](/guides/main_concepts/documents.md#primary-key) | +| **document_id** | [The document id](/learn/core_concepts/documents.md#primary-key) | ### Example @@ -248,7 +248,7 @@ Delete one document based on its unique id. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Delete documents @@ -282,4 +282,4 @@ The body must be a **JSON Array** with the unique id's of the documents to delet } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/dump.md b/reference/api/dump.md similarity index 67% rename from references/dump.md rename to reference/api/dump.md index 39bb1aa3cc..d0374c7a5e 100644 --- a/references/dump.md +++ b/reference/api/dump.md @@ -4,17 +4,17 @@ The `dumps` route allows the creation of database dumps. Dumps are `.dump` files Creating a dump is also referred to as exporting it, whereas launching MeiliSearch with a dump is referred to as importing it. -During a [dump export](/references/dump.md#create-a-dump), all indexes of the current instance are exported—together with their documents and settings—and saved as a single `.dump` file. +During a [dump export](/reference/api/dump.md#create-a-dump), all indexes of the current instance are exported—together with their documents and settings—and saved as a single `.dump` file. During a dump import, all indexes contained in the indicated `.dump` file are imported along with their associated documents and settings. Any existing index with the same uid as an index in the dump file will be overwritten. -Dump imports are [performed at launch](/guides/advanced_guides/configuration.md#import-dump) using an option. [Batch size](/guides/advanced_guides/configuration.md#dump-batch-size) can also be set at this time. +Dump imports are [performed at launch](/reference/features/configuration.md#import-dump) using an option. [Batch size](/reference/features/configuration.md#dump-batch-size) can also be set at this time. ## Create a Dump -Triggers a dump creation process. Once the process is complete, a dump is created in the [dumps directory](/guides/advanced_guides/configuration.md#dumps-destination). If the dumps directory does not exist yet, it will be created. +Triggers a dump creation process. Once the process is complete, a dump is created in the [dumps directory](/reference/features/configuration.md#dumps-destination). If the dumps directory does not exist yet, it will be created. ### Example @@ -33,7 +33,7 @@ Triggers a dump creation process. Once the process is complete, a dump is create -Get the status of a dump creation process using the uid returned after calling the [dump creation route](/references/dump.md#create-a-dump). +Get the status of a dump creation process using the uid returned after calling the [dump creation route](/reference/api/dump.md#create-a-dump). The returned status could be: - `in_progress`: Dump creation is in progress. diff --git a/references/health.md b/reference/api/health.md similarity index 100% rename from references/health.md rename to reference/api/health.md diff --git a/references/indexes.md b/reference/api/indexes.md similarity index 77% rename from references/indexes.md rename to reference/api/indexes.md index 72c88033bd..02a752ab2b 100644 --- a/references/indexes.md +++ b/reference/api/indexes.md @@ -1,14 +1,14 @@ # Indexes -An index is an entity that gathers a set of [documents](/guides/main_concepts/documents.md) with its own settings. +An index is an entity that gathers a set of [documents](/learn/core_concepts/documents.md) with its own settings. -[Learn more about indexes](/guides/main_concepts/indexes.md). +[Learn more about indexes](/learn/core_concepts/indexes.md). ## List all indexes -List all [indexes](/guides/main_concepts/indexes.md). +List all [indexes](/learn/core_concepts/indexes.md). ### Example @@ -37,7 +37,7 @@ List all [indexes](/guides/main_concepts/indexes.md). -Get information about an [index](/guides/main_concepts/indexes.md). +Get information about an [index](/learn/core_concepts/indexes.md). #### Path Variables @@ -64,12 +64,12 @@ Get information about an [index](/guides/main_concepts/indexes.md). -Create an [index](/guides/main_concepts/indexes.md). +Create an [index](/learn/core_concepts/indexes.md). -This route takes as parameter an unique `uid` and **optionally** the [primary key](/guides/main_concepts/indexes.md#primary-key). +This route takes as parameter an unique `uid` and **optionally** the [primary key](/learn/core_concepts/indexes.md#primary-key). ::: note -An index is automatically created when adding [documents](/references/documents.md) or [settings](/references/settings.md) to an index that does not already exist. +An index is automatically created when adding [documents](/reference/api/documents.md) or [settings](/reference/api/settings.md) to an index that does not already exist. ::: #### Body @@ -105,7 +105,7 @@ An index is automatically created when adding [documents](/references/documents. -Update an [index](/guides/main_concepts/indexes.md). +Update an [index](/learn/core_concepts/indexes.md). #### Path Variables @@ -120,9 +120,9 @@ Update an [index](/guides/main_concepts/indexes.md). | **primaryKey** | The of the documents | The `uid` of an index cannot be changed. -The `primaryKey` can be added if it does not already exist (to know if it has been set, use [the get index route](/references/indexes.md#get-one-index)). +The `primaryKey` can be added if it does not already exist (to know if it has been set, use [the get index route](/reference/api/indexes.md#get-one-index)). -[There are many ways in MeiliSearch to set the primary key](/guides/main_concepts/documents.md#primary-key). +[There are many ways in MeiliSearch to set the primary key](/learn/core_concepts/documents.md#primary-key). ### Example @@ -143,7 +143,7 @@ The `primaryKey` can be added if it does not already exist (to know if it has be -Delete an [index](/guides/main_concepts/indexes.md). +Delete an [index](/learn/core_concepts/indexes.md). #### Path Variables diff --git a/references/keys.md b/reference/api/keys.md similarity index 76% rename from references/keys.md rename to reference/api/keys.md index 42234a64a9..84e1fe72da 100644 --- a/references/keys.md +++ b/reference/api/keys.md @@ -4,13 +4,13 @@ Each instance of MeiliSearch has three keys: a master, a private, and a public. You must have the master key to access the `keys` route. -[More information about the keys and their rights](/guides/advanced_guides/authentication.md). +[More information about the keys and their rights](/reference/features/authentication.md). ## Get keys -Get the **private** and **public** [key](/guides/advanced_guides/authentication.md). +Get the **private** and **public** [key](/reference/features/authentication.md). ::: warning You must have the master key to access this route. diff --git a/references/ranking_rules.md b/reference/api/ranking_rules.md similarity index 71% rename from references/ranking_rules.md rename to reference/api/ranking_rules.md index d52d8cd9c5..e8d762529c 100644 --- a/references/ranking_rules.md +++ b/reference/api/ranking_rules.md @@ -1,12 +1,12 @@ # Ranking rules -_Child route of the [settings route](/references/settings.md)._ +_Child route of the [settings route](/reference/api/settings.md)._ Ranking rules are built-in rules that **ensure relevancy in search results**. Ranking rules are applied in a default order which can be changed in the settings. You can add or remove rules and change their order of importance. -Ranking rules can also be updated directly through the [global settings route](/references/settings.md#update-settings) along with the other settings. +Ranking rules can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. -[Learn more about ranking rules and their relevancy](/guides/main_concepts/relevancy.md). +[Learn more about ranking rules and their relevancy](/learn/core_concepts/relevancy.md). ::: note Updating the settings means overwriting the default settings of MeiliSearch. You can reset to default values using the `DELETE` routes. @@ -16,7 +16,7 @@ Updating the settings means overwriting the default settings of MeiliSearch. You -Get the [ranking rules](/guides/main_concepts/relevancy.md#ranking-rules) of an index. +Get the [ranking rules](/learn/core_concepts/relevancy.md#ranking-rules) of an index. #### Path Variables @@ -26,7 +26,7 @@ Get the [ranking rules](/guides/main_concepts/relevancy.md#ranking-rules) of an #### Default value -An array that contains [built-in ranking rules](/guides/main_concepts/relevancy.md#order-of-the-rules) sorted by order of importance. +An array that contains [built-in ranking rules](/learn/core_concepts/relevancy.md#order-of-the-rules) sorted by order of importance. ### Example @@ -52,7 +52,7 @@ List the settings. -Update the [ranking rules](/guides/main_concepts/relevancy.md#ranking-rules) of an index. +Update the [ranking rules](/learn/core_concepts/relevancy.md#ranking-rules) of an index. #### Path Variables @@ -70,7 +70,7 @@ To add your own ranking rule, you have to communicate either `asc` for ascending - To apply a **descending sorting** (results sorted by decreasing value of the attribute): `desc(attribute_name)` -[More information about the body](/guides/advanced_guides/settings.md#ranking-rules). +[More information about the body](/reference/features/settings.md#ranking-rules). ### Example @@ -84,23 +84,23 @@ To add your own ranking rule, you have to communicate either `asc` for ascending } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Reset ranking rules -Reset the [ranking rules](/guides/main_concepts/relevancy.md#ranking-rules) of an index to its default value. +Reset the [ranking rules](/learn/core_concepts/relevancy.md#ranking-rules) of an index to its default value. #### Default value -An array that contains [built-in ranking rules](/guides/main_concepts/relevancy.md#order-of-the-rules) sorted by order of importance. +An array that contains [built-in ranking rules](/learn/core_concepts/relevancy.md#order-of-the-rules) sorted by order of importance. ```json ["typo", "words", "proximity", "attribute", "wordsPosition", "exactness"] ``` -To remove all ranking rules, which is not recommended in any case, you would send an empty array to the [add or replace ranking rules route](/references/ranking_rules.md#update-ranking-rules). +To remove all ranking rules, which is not recommended in any case, you would send an empty array to the [add or replace ranking rules route](/reference/api/ranking_rules.md#update-ranking-rules). #### Path Variables @@ -120,4 +120,4 @@ To remove all ranking rules, which is not recommended in any case, you would sen } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/search.md b/reference/api/search.md similarity index 75% rename from references/search.md rename to reference/api/search.md index 46dfec5634..8ba330cdfa 100644 --- a/references/search.md +++ b/reference/api/search.md @@ -36,10 +36,10 @@ This is the preferred route to perform search when an API key is required, as it | **cropLength** | `Integer` | Length used to crop field values | `200` | | **attributesToHighlight** | `[Strings]` | Attributes whose values will contain highlighted matching terms | `null` | | **matches** | `Boolean` | Defines whether an object that contains information about the matches should be returned or not | `false` | -> `filters` accept a query string. You can find more about the filter syntax on [our dedicated page](/guides/advanced_guides/filtering.md). +> `filters` accept a query string. You can find more about the filter syntax on [our dedicated page](/reference/features/filtering.md). > `cropLength` is automatically rounded to match word boundaries. -[Learn more about how to use the search parameters](/guides/advanced_guides/search_parameters.md). +[Learn more about how to use the search parameters](/reference/features/search_parameters.md). ### Response @@ -50,7 +50,7 @@ This is the preferred route to perform search when an API key is required, as it | **limit** | Number of documents to take | `number` | | **nbHits** | Total number of matches | `number` | | **exhaustiveNbHits** | Whether `nbHits` is exhaustive | `boolean` | -| **facetsDistribution** | **[Distribution of the given facets](/guides/advanced_guides/search_parameters.md#the-facets-distribution)** | `object` +| **facetsDistribution** | **[Distribution of the given facets](/reference/features/search_parameters.md#the-facets-distribution)** | `object` | **exhaustiveFacetsCount** | Whether `facetsDistribution` is exhaustive | `boolean` | **processingTimeMs** | Processing time of the query | `number` | | **query** | Query originating the response | `string` | @@ -102,8 +102,6 @@ Search for documents matching a specific query in the given index. This route should only be used when no API key is required. If an API key is required, use the POST route instead. -[Learn more about how the search works](/guides/main_concepts/search.md). - #### Path Variables | Variable | Description | @@ -114,26 +112,26 @@ This route should only be used when no API key is required. If an API key is req | Query Parameter | Description | Default Value | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | :-----------: | -| **[q](/guides/advanced_guides/search_parameters.md#query-q)** | Query string | `""` | -| **[offset](/guides/advanced_guides/search_parameters.md#offset)** | Number of documents to skip | `0` | -| **[limit](/guides/advanced_guides/search_parameters.md#limit)** | Maximum number of documents returned | `20` | -| **[filters](/guides/advanced_guides/search_parameters.md#filters)** | Filter queries by an attribute value | `null` | -| **[facetFilters](/guides/advanced_guides/search_parameters.md#facet-filters)** | Facet names and values to filter on | `null` | -| **[facetsDistribution](/guides/advanced_guides/search_parameters.md#the-facets-distribution)** | Facets for which to retrieve the matching count | `null` | -| **[attributesToRetrieve](/guides/advanced_guides/search_parameters.md#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | -| **[attributesToCrop](/guides/advanced_guides/search_parameters.md#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | -| **[cropLength](/guides/advanced_guides/search_parameters.md#crop-length)** | Length used to crop field values | `200` | -| **[attributesToHighlight](/guides/advanced_guides/search_parameters.md#attributes-to-highlight)** | Attributes whose values will contain highlighted matching terms | `null` | -| **[matches](/guides/advanced_guides/search_parameters.md#matches)** | Defines whether an object that contains information about the matches should be returned or not | `false` | - -> `filters` accept a query string. You can find about the filter syntax on [our dedicated page](/guides/advanced_guides/filtering.md). +| **[q](/reference/features/search_parameters.md#query-q)** | Query string | `""` | +| **[offset](/reference/features/search_parameters.md#offset)** | Number of documents to skip | `0` | +| **[limit](/reference/features/search_parameters.md#limit)** | Maximum number of documents returned | `20` | +| **[filters](/reference/features/search_parameters.md#filters)** | Filter queries by an attribute value | `null` | +| **[facetFilters](/reference/features/search_parameters.md#facet-filters)** | Facet names and values to filter on | `null` | +| **[facetsDistribution](/reference/features/search_parameters.md#the-facets-distribution)** | Facets for which to retrieve the matching count | `null` | +| **[attributesToRetrieve](/reference/features/search_parameters.md#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | +| **[attributesToCrop](/reference/features/search_parameters.md#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | +| **[cropLength](/reference/features/search_parameters.md#crop-length)** | Length used to crop field values | `200` | +| **[attributesToHighlight](/reference/features/search_parameters.md#attributes-to-highlight)** | Attributes whose values will contain highlighted matching terms | `null` | +| **[matches](/reference/features/search_parameters.md#matches)** | Defines whether an object that contains information about the matches should be returned or not | `false` | + +> `filters` accept a query string. You can find about the filter syntax on [our dedicated page](/reference/features/filtering.md). > `cropLength` is automatically rounded to match word boundaries. -[Learn more about how to use the search parameters](/guides/advanced_guides/search_parameters.md). +[Learn more about how to use the search parameters](/reference/features/search_parameters.md). #### Placeholder Search -When the `q` parameter is not specified, a [placeholder](/guides/advanced_guides/search_parameters.md#query-q) search is run instead. +When the `q` parameter is not specified, a [placeholder](/reference/features/search_parameters.md#query-q) search is run instead. ### Response @@ -144,7 +142,7 @@ When the `q` parameter is not specified, a [placeholder](/guides/advanced_guides | **limit** | Number of documents to take | `number` | | **nbHits** | Total number of matches | `number` | | **exhaustiveNbHits** | Whether `nbHits` is exhaustive | `boolean` | -| **facetsDistribution** | **[Distribution of the given facets](/guides/advanced_guides/search_parameters.md#the-facets-distribution)** | `object` +| **facetsDistribution** | **[Distribution of the given facets](/reference/features/search_parameters.md#the-facets-distribution)** | `object` | **exhaustiveFacetsCount** | Whether `facetsDistribution` is exhaustive | `boolean` | **processingTimeMs** | Processing time of the query | `number` | | **query** | Query originating the response | `string` | diff --git a/references/searchable_attributes.md b/reference/api/searchable_attributes.md similarity index 72% rename from references/searchable_attributes.md rename to reference/api/searchable_attributes.md index befd1b2891..a977ab0f2c 100644 --- a/references/searchable_attributes.md +++ b/reference/api/searchable_attributes.md @@ -1,22 +1,22 @@ # Searchable attributes -_Child route of the [settings route](/references/settings.md)._ +_Child route of the [settings route](/reference/api/settings.md)._ -The values associated with attributes in the `searchableAttributes` list are **searched for matching query words**. The order of the list also determines the [attribute ranking order](/guides/main_concepts/relevancy.md#attribute-ranking-order). +The values associated with attributes in the `searchableAttributes` list are **searched for matching query words**. The order of the list also determines the [attribute ranking order](/learn/core_concepts/relevancy.md#attribute-ranking-order). -Searchable attributes can also be updated directly through the [global settings route](/references/settings.md#update-settings) along with the other settings. +Searchable attributes can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. ::: note Updating the settings means overwriting the default settings of MeiliSearch. You can reset to default values using the `DELETE` routes. ::: -[Learn more about searchable fields](/guides/advanced_guides/field_properties.md#searchable-fields). +[Learn more about searchable fields](/reference/features/field_properties.md#searchable-fields). ## Get searchable attributes -Get the [searchable attributes](/guides/advanced_guides/field_properties.md#searchable-fields) of an index. +Get the [searchable attributes](/reference/features/field_properties.md#searchable-fields) of an index. #### Path Variables @@ -40,7 +40,7 @@ List the settings. -Update the [searchable attributes](/guides/advanced_guides/field_properties.md#searchable-fields) of an index. +Update the [searchable attributes](/reference/features/field_properties.md#searchable-fields) of an index. #### Path Variables @@ -54,7 +54,7 @@ An array of strings that contains searchable attributes sorted by order of impor This means that a document with a match in an attribute at the start of the array will be considered more relevant than a document with a match in an attribute at the end of the array. -[More information about the body](/guides/advanced_guides/settings.md#searchable-attributes). +[More information about the body](/reference/features/settings.md#searchable-attributes). ### Example @@ -70,13 +70,13 @@ A match in title will make a document more relevant than another document with a } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Reset searchable attributes -Reset the [searchable attributes](/guides/advanced_guides/field_properties.md#searchable-fields) of the index to the default value. +Reset the [searchable attributes](/reference/features/field_properties.md#searchable-fields) of the index to the default value. #### Default value @@ -100,4 +100,4 @@ All attributes found in the documents added to the index. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/settings.md b/reference/api/settings.md similarity index 83% rename from references/settings.md rename to reference/api/settings.md index 515335921b..582277b15a 100644 --- a/references/settings.md +++ b/reference/api/settings.md @@ -6,15 +6,15 @@ It is possible to update all the settings in one go or individually with the ded These are the reference pages for the dedicated routes: -- [Synonyms](/references/synonyms.md) -- [Stop-words](/references/stop_words.md) -- [Ranking rules](/references/ranking_rules.md) -- [Attributes For Faceting](/references/attributes_for_faceting.md) -- [Distinct attribute](/references/distinct_attribute.md) -- [Searchable attributes](/references/searchable_attributes.md) -- [Displayed attributes](/references/displayed_attributes.md) +- [Synonyms](/reference/api/synonyms.md) +- [Stop-words](/reference/api/stop_words.md) +- [Ranking rules](/reference/api/ranking_rules.md) +- [Attributes For Faceting](/reference/api/attributes_for_faceting.md) +- [Distinct attribute](/reference/api/distinct_attribute.md) +- [Searchable attributes](/reference/api/searchable_attributes.md) +- [Displayed attributes](/reference/api/displayed_attributes.md) -[Learn more about the settings in this guide](/guides/advanced_guides/settings.md) +[Learn more about the settings in this guide](/reference/features/settings.md) ::: note Updating the settings means overwriting the default settings of MeiliSearch. You can reset to default values using the `DELETE` routes. @@ -26,7 +26,7 @@ Updating the settings means overwriting the default settings of MeiliSearch. You Get the settings of an index. -[Learn more about the settings](/guides/advanced_guides/settings.md). +[Learn more about the settings](/reference/features/settings.md). #### Path Variables @@ -40,13 +40,13 @@ Get the settings of an index. | ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **synonyms** | Object | List of associated words treated similarly | `{}` | | **stopWords** | [Strings] | List of words ignored by MeiliSearch when present in search queries | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/guides/main_concepts/relevancy.md#order-of-the-rules) | -| **attributesForFaceting** | [Strings] | Attributes to use as [facets](/guides/advanced_guides/faceted_search.md) | `[]` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#order-of-the-rules) | +| **attributesForFaceting** | [Strings] | Attributes to use as [facets](/reference/features/faceted_search.md) | `[]` | | **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | | **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | | **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | -[Learn more about the settings in this guide](/guides/advanced_guides/settings.md) +[Learn more about the settings in this guide](/reference/features/settings.md) ### Example @@ -91,7 +91,7 @@ List the settings. Update the settings of an index. Updates in the settings route are **partial**. This means that any parameters not provided in the body will be left unchanged. -[Learn more about the settings in this guide](/guides/advanced_guides/settings.md). +[Learn more about the settings in this guide](/reference/features/settings.md). If the provided index does not exist, it will be created. @@ -107,8 +107,8 @@ If the provided index does not exist, it will be created. | ------------------------ | --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **synonyms** | Object | List of associated words treated similarly | `{}` | | **stopWords** | [Strings] | List of words ignored by MeiliSearch when present in search queries | `[]` | -| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/guides/main_concepts/relevancy.md#order-of-the-rules) | -| **attributesForFaceting** | [Strings] | Attributes to use as [facets](/guides/advanced_guides/faceted_search.md) | `[]` | +| **rankingRules** | [Strings] | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#order-of-the-rules) | +| **attributesForFaceting** | [Strings] | Attributes to use as [facets](/reference/features/faceted_search.md) | `[]` | | **distinctAttribute** | String | Search returns documents with distinct (different) values of the given field | `null` | | **searchableAttributes** | [Strings] | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | | **displayedAttributes** | [Strings] | Fields displayed in the returned documents | `["*"]` (all attributes) | @@ -125,7 +125,7 @@ If the provided index does not exist, it will be created. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Reset settings @@ -139,13 +139,13 @@ All settings will be reset to their default value. | ------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **synonyms** | List of associated words treated similarly | `{}` | | **stopWords** | List of words ignored by MeiliSearch when present in search queries | `[]` | -| **rankingRules** | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/guides/main_concepts/relevancy.md#order-of-the-rules) | -| **attributesForFaceting** | Attributes to use as [facets](/guides/advanced_guides/faceted_search.md) | `[]` | +| **rankingRules** | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#order-of-the-rules) | +| **attributesForFaceting** | Attributes to use as [facets](/reference/features/faceted_search.md) | `[]` | | **distinctAttribute** | Search returns documents with distinct (different) values of a given field | `null` | | **searchableAttributes** | Fields in which to search for matching query words sorted by order of importance | `["*"]` (all attributes) | | **displayedAttributes** | Fields displayed in the returned documents documents | `["*"]` (all attributes) | -[Learn more about the settings](/guides/advanced_guides/settings.md). +[Learn more about the settings](/reference/features/settings.md). #### Path Variables @@ -165,4 +165,4 @@ All settings will be reset to their default value. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/stats.md b/reference/api/stats.md similarity index 100% rename from references/stats.md rename to reference/api/stats.md diff --git a/references/stop_words.md b/reference/api/stop_words.md similarity index 71% rename from references/stop_words.md rename to reference/api/stop_words.md index 0d4173078c..2747532d8a 100644 --- a/references/stop_words.md +++ b/reference/api/stop_words.md @@ -1,12 +1,12 @@ # Stop-words -_Child route of the [settings route](/references/settings.md)._ +_Child route of the [settings route](/reference/api/settings.md)._ The stop-words route lets you add a list of words that will be ignored in search queries. So if you add `the` as a stop word and you make a search on `the mask` you will only have matching documents with `mask`. -Stop-words can also be updated directly through the [global settings route](/references/settings.md#update-settings) along with the other settings. +Stop-words can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. -[Learn more about stop words](/guides/advanced_guides/stop_words.md) +[Learn more about stop words](/reference/features/stop_words.md) ::: note Updating the settings means overwriting the default settings of MeiliSearch. You can reset to default values using the `DELETE` routes. @@ -16,7 +16,7 @@ Updating the settings means overwriting the default settings of MeiliSearch. You -Get the [stop-words](/guides/advanced_guides/stop_words.md) list of an index. +Get the [stop-words](/reference/features/stop_words.md) list of an index. #### Path Variables @@ -38,7 +38,7 @@ Get the [stop-words](/guides/advanced_guides/stop_words.md) list of an index. -Update the list of [stop-words](/guides/advanced_guides/stop_words.md) of an index. +Update the list of [stop-words](/reference/features/stop_words.md) of an index. #### Path Variables @@ -48,11 +48,11 @@ Update the list of [stop-words](/guides/advanced_guides/stop_words.md) of an ind #### Body -An array of strings that contains the [stop-words](/guides/advanced_guides/stop_words.md). +An array of strings that contains the [stop-words](/reference/features/stop_words.md). If a list of stop-words already exists it will be overwritten (_replaced_). -[More information about the body](/guides/advanced_guides/settings.md#stop-words). +[More information about the body](/reference/features/settings.md#stop-words). ### Example @@ -66,13 +66,13 @@ If a list of stop-words already exists it will be overwritten (_replaced_). } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Reset stop-words -Reset the list of [stop-words](/guides/advanced_guides/stop_words.md) of an index to its default value. +Reset the list of [stop-words](/reference/features/stop_words.md) of an index to its default value. #### Default value @@ -96,4 +96,4 @@ Empty array: `[]` } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/synonyms.md b/reference/api/synonyms.md similarity index 74% rename from references/synonyms.md rename to reference/api/synonyms.md index 9aa397dbae..98242e39a4 100644 --- a/references/synonyms.md +++ b/reference/api/synonyms.md @@ -1,22 +1,22 @@ # Synonyms -_Child route of the [settings route](/references/settings.md)._ +_Child route of the [settings route](/reference/api/settings.md)._ `Synonyms` is an object containing words and their respective synonyms. A synonym in Meilisearch is considered equal to its associated word in a search query. -Synonyms can also be updated directly through the [global settings route](/references/settings.md#update-settings) along with the other settings. +Synonyms can also be updated directly through the [global settings route](/reference/api/settings.md#update-settings) along with the other settings. ::: note Updating the settings means overwriting the default settings of MeiliSearch. You can reset to default values using the `DELETE` routes. ::: -[Learn more about synonyms](/guides/advanced_guides/synonyms.md) +[Learn more about synonyms](/reference/features/synonyms.md) ## Get synonyms -Get the list of [synonyms](/guides/advanced_guides/synonyms.md) of an index. +Get the list of [synonyms](/reference/features/synonyms.md) of an index. #### Path Variables @@ -42,7 +42,7 @@ Get the list of [synonyms](/guides/advanced_guides/synonyms.md) of an index. -Update the list of [synonyms](/guides/advanced_guides/synonyms.md) of an index. +Update the list of [synonyms](/reference/features/synonyms.md) of an index. #### Path Variables @@ -54,7 +54,7 @@ Update the list of [synonyms](/guides/advanced_guides/synonyms.md) of an index. An object that contains all synonyms and their associated words. -[More information about the body](/guides/advanced_guides/settings.md#synonyms). +[More information about the body](/reference/features/settings.md#synonyms). #### Example @@ -68,13 +68,13 @@ An object that contains all synonyms and their associated words. } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). ## Reset synonyms -Reset the list of [synonyms](/guides/advanced_guides/synonyms.md) of an index to its default value. +Reset the list of [synonyms](/reference/features/synonyms.md) of an index to its default value. #### Default value @@ -98,4 +98,4 @@ Empty object : `{}` } ``` -This `updateId` allows you to [track the current update](/references/updates.md). +This `updateId` allows you to [track the current update](/reference/api/updates.md). diff --git a/references/updates.md b/reference/api/updates.md similarity index 80% rename from references/updates.md rename to reference/api/updates.md index ec9457f7fe..13f93ae51e 100644 --- a/references/updates.md +++ b/reference/api/updates.md @@ -1,12 +1,12 @@ # Updates -The `updates` route gives information about the progress of the [asynchronous processes](/guides/advanced_guides/asynchronous_updates.md). +The `updates` route gives information about the progress of the [asynchronous processes](/learn/advanced/asynchronous_updates.md). ## Get an update status -Get the status of an [update](/guides/advanced_guides/asynchronous_updates.md) in a given [index](/guides/main_concepts/indexes.md). +Get the status of an [update](/learn/advanced/asynchronous_updates.md) in a given [index](/learn/core_concepts/indexes.md). #### Path Variables @@ -41,7 +41,7 @@ Here is an example response of an update that has been processed. -Get the status of all [updates](/guides/advanced_guides/asynchronous_updates.md) in a given [index](/guides/main_concepts/indexes.md). +Get the status of all [updates](/learn/advanced/asynchronous_updates.md) in a given [index](/learn/core_concepts/indexes.md). #### Path Variables diff --git a/references/version.md b/reference/api/version.md similarity index 100% rename from references/version.md rename to reference/api/version.md diff --git a/reference/features/README.md b/reference/features/README.md new file mode 100644 index 0000000000..2364a4d084 --- /dev/null +++ b/reference/features/README.md @@ -0,0 +1,25 @@ +# Feature Reference + +Want to know something about MeiliSearch? Chances are high that it's written down here. + +This section is where we document all of MeiliSearch's user-facing features and tools. This does not include [API routes](/reference/api) or [details of the MeiliSearch engine](/reference/under_the_hood); these each have their own section. + +Understanding our reference documentation is easier with background knowledge of MeiliSearch's [core concepts](/learn/core_concepts). If you're a **new user**, you might prefer to start with an [explanation of MeiliSearch's features](/learn/what_is_meilisearch/features.md) or a [guided tutorial](/learn/tutorials/). + +## Table of Contents + +[Authentication](/reference/features/authentication.md) +[Configuration](/reference/features/configuration.md) +[Distinct Attributes](/reference/features/distinct.md) +[Dumps](/reference/features/dumps.md) +[Faceted Search](/reference/features/faceted_search.md) +[Field Properties](/reference/features/field_properties.md) +[Filtering](/reference/features/filtering.md) +[Installation](/reference/features/installation.md) +[Known Limitations](/reference/features/known_limitations.md) +[Search Parameters](/reference/features/search_parameters.md) +[Settings](/reference/features/settings.md) +[Snapshots](/reference/features/snapshots.md) +[Stop Words](/reference/features/stop_words.md) +[Synonyms](/reference/features/synonyms.md) +[Web Interface](/reference/features/web_interface.md) diff --git a/guides/advanced_guides/authentication.md b/reference/features/authentication.md similarity index 94% rename from guides/advanced_guides/authentication.md rename to reference/features/authentication.md index 4302b3d9a4..75f6fce309 100644 --- a/guides/advanced_guides/authentication.md +++ b/reference/features/authentication.md @@ -20,7 +20,7 @@ When launching an instance, you have the option of giving a master key. By doing You can specify it by passing the `MEILI_MASTER_KEY` environment variable, or using the command line argument `--master-key`. -You can retrieve both the private and the public keys using the master key on the [keys route](/references/keys.md). +You can retrieve both the private and the public keys using the master key on the [keys route](/reference/api/keys.md). #### No master key @@ -28,7 +28,7 @@ If no master key is provided, all routes can be accessed without requiring any k ## API Key -If a master key is set, on each API call, a key must be added to [the header](/references/#authentication). +If a master key is set, on each API call, a key must be added to [the header](/reference/api/README.md#authentication). If no or a wrong API key is provided in the header you will have no access to any route and you will receive the `HTTP/1.1 403 Forbidden` status code. diff --git a/guides/advanced_guides/configuration.md b/reference/features/configuration.md similarity index 75% rename from guides/advanced_guides/configuration.md rename to reference/features/configuration.md index fdabce04e4..ac667c1684 100644 --- a/guides/advanced_guides/configuration.md +++ b/reference/features/configuration.md @@ -28,37 +28,37 @@ Server is listening on: http://127.0.0.1:7700 #### General -- [Database path](/guides/advanced_guides/configuration.md#database-path) -- [HTTP address & port binding](/guides/advanced_guides/configuration.md#http-address-port-binding) -- [Master key](/guides/advanced_guides/configuration.md#master-key) -- [Environment](/guides/advanced_guides/configuration.md#environment) +- [Database path](/reference/features/configuration.md#database-path) +- [HTTP address & port binding](/reference/features/configuration.md#http-address-port-binding) +- [Master key](/reference/features/configuration.md#master-key) +- [Environment](/reference/features/configuration.md#environment) #### Advanced -- [Analytics](/guides/advanced_guides/configuration.md#analytics) -- [Payload Limit Size](/guides/advanced_guides/configuration.md#payload-limit-size) -- [Snapshots](/guides/advanced_guides/configuration.md#schedule-snapshot-creation): - - [Schedule Snapchot Creation](/guides/advanced_guides/configuration.md#schedule-snapshot-creation) - - [Snapshot Destination](/guides/advanced_guides/configuration.md#snapshot-destination) - - [Snapshot Interval](/guides/advanced_guides/configuration.md#snapshot-interval) - - [Import Snapshot](/guides/advanced_guides/configuration.md#import-snapshot) - - [Ignore Missing Snapshot](/guides/advanced_guides/configuration.md#ignore-missing-snapshot) - - [Ignore Snapshot if DB Exists](/guides/advanced_guides/configuration.md#ignore-snapshot-if-db-exists) -- [Dumps](/guides/advanced_guides/configuration.md#dumps-destination) - - [Dumps Destination](/guides/advanced_guides/configuration.md#dumps-destination) - - [Import Dump](/guides/advanced_guides/configuration.md#import-dump) - - [Dump Batch Size](/guides/advanced_guides/configuration.md#dump-batch-size) -- [Max MDB Size](/guides/advanced_guides/configuration.md#max-mdb-size) -- [Max UDB Size](/guides/advanced_guides/configuration.md#max-udb-size) -- [SSL Configuration](/guides/advanced_guides/configuration.md#ssl-authentication-path): - - [SSL Authentication Path](/guides/advanced_guides/configuration.md#ssl-authentication-path) - - [SSL Certicates Path](/guides/advanced_guides/configuration.md#ssl-certificates-path) - - [SSL Key Path](/guides/advanced_guides/configuration.md#ssl-key-path) - - [SSL OCSP Path](/guides/advanced_guides/configuration.md#ssl-ocsp-path) - - [SSL Require Auth](/guides/advanced_guides/configuration.md#ssl-require-auth) - - [SSL Resumption](/guides/advanced_guides/configuration.md#ssl-resumption) - - [SSL Tickets](/guides/advanced_guides/configuration.md#ssl-tickets) -- [Disable Sentry](/guides/advanced_guides/configuration.md#disable-sentry) +- [Analytics](/reference/features/configuration.md#analytics) +- [Payload Limit Size](/reference/features/configuration.md#payload-limit-size) +- [Snapshots](/reference/features/configuration.md#schedule-snapshot-creation): + - [Schedule Snapchot Creation](/reference/features/configuration.md#schedule-snapshot-creation) + - [Snapshot Destination](/reference/features/configuration.md#snapshot-destination) + - [Snapshot Interval](/reference/features/configuration.md#snapshot-interval) + - [Import Snapshot](/reference/features/configuration.md#import-snapshot) + - [Ignore Missing Snapshot](/reference/features/configuration.md#ignore-missing-snapshot) + - [Ignore Snapshot if DB Exists](/reference/features/configuration.md#ignore-snapshot-if-db-exists) +- [Dumps](/reference/features/configuration.md#dumps-destination) + - [Dumps Destination](/reference/features/configuration.md#dumps-destination) + - [Import Dump](/reference/features/configuration.md#import-dump) + - [Dump Batch Size](/reference/features/configuration.md#dump-batch-size) +- [Max MDB Size](/reference/features/configuration.md#max-mdb-size) +- [Max UDB Size](/reference/features/configuration.md#max-udb-size) +- [SSL Configuration](/reference/features/configuration.md#ssl-authentication-path): + - [SSL Authentication Path](/reference/features/configuration.md#ssl-authentication-path) + - [SSL Certicates Path](/reference/features/configuration.md#ssl-certificates-path) + - [SSL Key Path](/reference/features/configuration.md#ssl-key-path) + - [SSL OCSP Path](/reference/features/configuration.md#ssl-ocsp-path) + - [SSL Require Auth](/reference/features/configuration.md#ssl-require-auth) + - [SSL Resumption](/reference/features/configuration.md#ssl-resumption) + - [SSL Tickets](/reference/features/configuration.md#ssl-tickets) +- [Disable Sentry](/reference/features/configuration.md#disable-sentry) ### Database path @@ -85,7 +85,7 @@ The address the HTTP server will listen on. The master key allowing you to do everything on the server. If no master key is provided all routes will be accessible without keys. This is only possible if you are in `development` environment. An error is thrown if you try to start MeiliSearch without any master key when the environment is set to `production`. -[Learn more about the permission and authentication in this guide.](/guides/advanced_guides/authentication.md) +[Learn more about the permission and authentication in this guide.](/reference/features/authentication.md) **Default value**: `None` @@ -117,12 +117,12 @@ Analytics allow us to know how many users are using MeiliSearch and the followin By default, MeiliSearch runs in `development` mode. -- `production`: the [master key](/guides/advanced_guides/authentication.md) is **mandatory**. -- `development`: the [master key](/guides/advanced_guides/authentication.md) is **optional**, and logs are output in "info" mode (_console output_). +- `production`: the [master key](/reference/features/authentication.md) is **mandatory**. +- `development`: the [master key](/reference/features/authentication.md) is **optional**, and logs are output in "info" mode (_console output_). If the server is running in development mode more logs will be displayed, and the master key can be avoided which implies that there is no security on the updates routes. This is useful to debug when integrating the engine with another service. -In production mode, the [web interface](/guides/advanced_guides/web_interface.md#web-interface) is disabled. +In production mode, the [web interface](/reference/features/web_interface.md#web-interface) is disabled. **Default value**: `development` @@ -218,7 +218,7 @@ Depending on the OS, it is either the size that will be allocated on launch or t - On **Windows** it is a fixed size that will be allocated on launch. Because this allocates 100Gb on MeiliSearch launch, a Windows user can use this option to decrease the size of the database. -[To know more about storage in MeiliSearch look at this guide](/resources/about_storage.md) +[To know more about storage in MeiliSearch look at this guide](/reference/under_the_hood/storage.md) **Default value**: `107374182400` (100 GiB) @@ -227,7 +227,7 @@ Depending on the OS, it is either the size that will be allocated on launch or t **Environment variable**: `MEILI_MAX_UDB_SIZE` **CLI option**: `--max-udb-size` -The maximum size, in bytes, of the `update` database. The `update` database stores the [pending updates](/guides/advanced_guides/asynchronous_updates.md). +The maximum size, in bytes, of the `update` database. The `update` database stores the [pending updates](/learn/advanced/asynchronous_updates.md). The size must be a modulo value of your OS `PAGE_SIZE` otherwise it will throw an error. You can find out about the `PAGE_SIZE` with the following command: @@ -242,7 +242,7 @@ Depending on the OS, it is either the size that will be allocated on launch or t - On **Windows** it is a fixed size that will be allocated on launch. Because this allocates 100Gb on MeiliSearch launch, a Windows user can use this option to decrease the size of the database. -[To know more about storage in MeiliSearch look at this guide](/resources/about_storage.md) +[To know more about storage in MeiliSearch look at this guide](/reference/under_the_hood/storage.md) **Default value**: `107374182400` (100 GiB) @@ -262,7 +262,7 @@ Activates scheduled snapshots. If this command is not added or its value is `false` snapshotting is deactivated. -[Read more about snapshots](/guides/advanced_guides/snapshots_and_dumps.md#snapshots). +[Read more about snapshots](/reference/features/snapshots.md). ### Snapshot Destination @@ -316,7 +316,7 @@ Requires `--import-snapshot` to be defined. **Environment variable**: `MEILI_DUMPS_DIR` **CLI option**: `--dumps-dir` -Path of the directory where dumps will be created if the [dump route](/references/dump.md#create-a-dump) is called. +Path of the directory where dumps will be created if the [dump route](/reference/api/dump.md#create-a-dump) is called. **Default value**: `dumps/` @@ -348,4 +348,4 @@ Imagine you set `--dump-batch-size 1000` and your dump contains 2600 documents. **Default value**: `1024` -[Read more about dumps](/guides/advanced_guides/snapshots_and_dumps.md#dumps) +[Read more about dumps](/reference/features/dumps.md) diff --git a/guides/advanced_guides/distinct.md b/reference/features/distinct.md similarity index 88% rename from guides/advanced_guides/distinct.md rename to reference/features/distinct.md index 2d3a650473..1af4e05be2 100644 --- a/guides/advanced_guides/distinct.md +++ b/reference/features/distinct.md @@ -40,7 +40,7 @@ You may want to ignore the different colors of an item. To do so, you can set `p -By [setting `product_id` as a distinct attribute](/references/distinct_attribute.md), search requests **will never return more than one jacket with the same `product_id`**. +By [setting `product_id` as a distinct attribute](/reference/api/distinct_attribute.md), search requests **will never return more than one jacket with the same `product_id`**. ::: warning If the field does not exist, no error will be thrown. diff --git a/reference/features/dumps.md b/reference/features/dumps.md new file mode 100644 index 0000000000..cc6cf1bd54 --- /dev/null +++ b/reference/features/dumps.md @@ -0,0 +1,33 @@ +# Dumps + +A dump is a compressed file containing an export of your MeiliSearch instance. It contains all your indexes, documents, and settings, but in a raw unprocessed form. A dump isn't an exact copy of your database—it is closer to a blueprint that allows you to create an identical dataset. A dump can be imported when launching MeiliSearch, but be advised that it may take some time to index all the documents within. + +## Creating a Dump + +To create a dump of your dataset, you need to use the appropriate HTTP route: `POST /dumps`. Using that route will trigger a dump creation process. Creating a dump is an asynchronous task that takes time based on the size of your dataset. A dump uid (unique identifier) is returned to help you track the process. + + + +The above code triggers a dump creation process. + +At any given moment, you can check the status of a particular dump creation process using the previously received dump uid, like so: `GET /dumps/:dump_uid/status`. Using this route, you can know whether your dump is still processing, has already been created, or has encountered a problem. + + + +After your dump creation process is done, the dump file is created and added in the dump folder. By default, this folder is `/dumps` at the root of your MeiliSearch binary, but this can be customized. Note that **if your dump folder does not already exist when the dump creation process is called, MeiliSearch will create it**. + +## Importing a Dump + +Once you have exported a dump, which is a `.dump` file, you are now able to use that dump to launch MeiliSearch. As the data contained in the dump needs to be indexed, the process will take some time to complete. Only when the dump has been fully imported will the MeiliSearch server start, after which you can begin searching through your data. + +```bash +./meilisearch --import-dump /dumps/20200813-042312213.dump +``` + +Because importing a dump is the same process as when documents are initially indexed by MeiliSearch, it can require some time and memory. If your dataset is very large, it is good practice to index documents in larger batches. This will speed up the indexing process at the cost of memory. + +[See here for more dumps options](/reference/features/configuration.md#dumps-destination) + +## Use Cases + +Dumps are used to restore your database after MeiliSearch updates or to communicate your database to other instances of MeiliSearch (e.g. running on different servers) without having to worry about their respective versions. diff --git a/guides/advanced_guides/faceted_search.md b/reference/features/faceted_search.md similarity index 95% rename from guides/advanced_guides/faceted_search.md rename to reference/features/faceted_search.md index 3e051e929d..20cfad3943 100644 --- a/guides/advanced_guides/faceted_search.md +++ b/reference/features/faceted_search.md @@ -15,7 +15,7 @@ Faceted search, also known as faceted navigation, is a technique that combines t Setting categorical document attributes as "facet" enables efficient filtering within the different categories. Such categorical attributes are, for example, movie genre, director, or language. Besides, faceting is a powerful feature that allows building intuitive navigation interfaces. -Both faceting and filtering help drill down into a subset of search results. However, **faceting differs from [filtering](/guides/advanced_guides/filtering.md)**. +Both faceting and filtering help drill down into a subset of search results. However, **faceting differs from [filtering](/reference/features/filtering.md)**. - **Filters** exclude some results based on criteria. They allow users to narrow down a set of documents to only those matching these chosen criteria. In other words, filtering is used to filter the returned results by adding constraints. - **Facets**, on the other hand, are used to categorize the data into subsets that will be searched upon: they reduce the number of documents to process. @@ -26,13 +26,13 @@ Faceting and filtering aim at being complementary; facets narrows down the set The first step in using facets is to chose which of your document will be used as facets. Fields with common values are the best suited for faceting (e.g., `genre`, `color`, `size` ). -For these fields to be used as facets during search, their **must have been previously added to the settings**. In the settings, the chosen attributes must be added to the [`attributesForFaceting` list](/guides/advanced_guides/settings.md#attributes-for-faceting). +For these fields to be used as facets during search, their **must have been previously added to the settings**. In the settings, the chosen attributes must be added to the [`attributesForFaceting` list](/reference/features/settings.md#attributes-for-faceting). This step is required because facet needs to be properly processed and prepared by the engine to be usable. This process takes as much time as indexing all your documents. You can perform faceting on attributes that are either `String` or `[String]`, and `null` values are ignored. If a facet value in a given document is **not** of type `string`, or `[String]`, or `null`, the transaction will stop and raise an error. -[References for `attributesForFaceting` in the settings](/guides/advanced_guides/settings.md#attributes-for-faceting) +[References for `attributesForFaceting` in the settings](/reference/features/settings.md#attributes-for-faceting) #### Example @@ -80,7 +80,7 @@ They can filter on facets to narrow down their results based on criteria with th `facetFilters=["facetName:facetValue"]` or `facetFilters=[["facetName:facetValue"]]` -- `facetName`: The name (the attribute) of a field used as a facet (e.g. `director`, `genres`). This attribute must be [in the `attributesForFaceting` list](/guides/advanced_guides/faceted_search.md#setting-up-facets). +- `facetName`: The name (the attribute) of a field used as a facet (e.g. `director`, `genres`). This attribute must be [in the `attributesForFaceting` list](/reference/features/faceted_search.md#setting-up-facets). - `facetValue`: The value of the facet used to filter results (e.g. `Tim Burton`, `Mati Diop`, `Comedy`, `Romance`). Facet filters can have a **maximum array deepness of two**. @@ -139,7 +139,7 @@ Can be translated as: #### Example -Suppose you have declared `director` and `genres` as [faceted attributes](/guides/advanced_guides/settings.md#attributes-for-faceting), and you want to get movies matching "thriller" classified as either horror **or** mystery **and** directed by Jordan Peele. +Suppose you have declared `director` and `genres` as [faceted attributes](/reference/features/settings.md#attributes-for-faceting), and you want to get movies matching "thriller" classified as either horror **or** mystery **and** directed by Jordan Peele. ```SQL ("genres:Horror" OR "genres:Mystery") AND "director:Jordan Peele" diff --git a/guides/advanced_guides/field_properties.md b/reference/features/field_properties.md similarity index 71% rename from guides/advanced_guides/field_properties.md rename to reference/features/field_properties.md index a6e4ee6eb0..1ab27dba81 100644 --- a/guides/advanced_guides/field_properties.md +++ b/reference/features/field_properties.md @@ -2,10 +2,10 @@ By default, whenever a document is added to MeiliSearch, all new attributes found in it are automatically added to two lists: -- **The [searchable attributes list](/guides/advanced_guides/field_properties.md#the-searchable-attributes-list)**: Attributes whose fields are searched for matching query words. -- **The [displayed attributes list](/guides/advanced_guides/field_properties.md#displayed-fields)**: Attributes whose fields are displayed in documents. +- **The [searchable attributes list](/reference/features/field_properties.md#the-searchable-attributes-list)**: Attributes whose fields are searched for matching query words. +- **The [displayed attributes list](/reference/features/field_properties.md#displayed-fields)**: Attributes whose fields are displayed in documents. -This means that by default, every field in a document is **searchable** and **displayed**. These properties can be modified in the [settings](/references/settings.md). +This means that by default, every field in a document is **searchable** and **displayed**. These properties can be modified in the [settings](/reference/api/settings.md). ## Searchable Fields @@ -21,12 +21,12 @@ Even if you make a field non-searchable, it will remain stored in the database a ### The Searchable Attributes List -MeiliSearch uses an ordered list to determine which attributes are searchable. The order in which attributes appear in this list also determines their [impact on relevancy](/guides/main_concepts/relevancy.md#attribute-ranking-order), from most impactful to least. +MeiliSearch uses an ordered list to determine which attributes are searchable. The order in which attributes appear in this list also determines their [impact on relevancy](/learn/core_concepts/relevancy.md#attribute-ranking-order), from most impactful to least. In other words, the `searchableAttributes` list serves two purposes: 1. It designates the fields that are searchable. -2. It dictates the [attribute ranking order](/guides/main_concepts/relevancy.md#attribute-ranking-order). +2. It dictates the [attribute ranking order](/learn/core_concepts/relevancy.md#attribute-ranking-order). There are two possible modes for the `searchableAttributes` list. @@ -34,16 +34,16 @@ There are two possible modes for the `searchableAttributes` list. **By default, all attributes are automatically added to the `searchableAttributes` list in their order of appearance.** This means that the initial order will be based on the order of attributes in the first document indexed, with each new attribute found in subsequent documents added at the end of this list. -This default behavior is indicated by a `searchableAttributes` value of `["*"]`. To verify the current value of your `searchableAttributes` list, use the [get searchable attributes endpoint](/references/searchable_attributes.md#get-searchable-attributes). +This default behavior is indicated by a `searchableAttributes` value of `["*"]`. To verify the current value of your `searchableAttributes` list, use the [get searchable attributes endpoint](/reference/api/searchable_attributes.md#get-searchable-attributes). -If you'd like to restore your searchable attributes list to this default behavior, simply [set `searchableAttributes` to an empty array `[]`](/references/searchable_attributes.md#update-searchable-attributes) or use the [reset searchable attributes endpoint](/references/searchable_attributes.md#reset-searchable-attributes). +If you'd like to restore your searchable attributes list to this default behavior, simply [set `searchableAttributes` to an empty array `[]`](/reference/api/searchable_attributes.md#update-searchable-attributes) or use the [reset searchable attributes endpoint](/reference/api/searchable_attributes.md#reset-searchable-attributes). #### Manual -You may want to make some attributes non-searchable, or change the [attribute ranking order](/guides/main_concepts/relevancy.md#attribute-ranking-order) after documents have been indexed. To do so, simply place the attributes in the desired order and send the updated list using the [update searchable attributes endpoint](/references/searchable_attributes.md#update-searchable-attributes). +You may want to make some attributes non-searchable, or change the [attribute ranking order](/learn/core_concepts/relevancy.md#attribute-ranking-order) after documents have been indexed. To do so, simply place the attributes in the desired order and send the updated list using the [update searchable attributes endpoint](/reference/api/searchable_attributes.md#update-searchable-attributes). ::: warning -Be aware that after manually updating the `searchableAttributes` list, subsequent new attributes will no longer be automatically added unless the settings are [reset](/references/searchable_attributes.md#reset-searchable-attributes). +Be aware that after manually updating the `searchableAttributes` list, subsequent new attributes will no longer be automatically added unless the settings are [reset](/reference/api/searchable_attributes.md#reset-searchable-attributes). ::: #### Example @@ -54,7 +54,7 @@ Suppose that you manage a database of movies with the following fields: `id`, `d ## Displayed Fields -The fields whose attributes are added to the [displayed-attributes list](/references/displayed_attributes.md) are **displayed in each matching document**. +The fields whose attributes are added to the [displayed-attributes list](/reference/api/displayed_attributes.md) are **displayed in each matching document**. Documents returned upon search contain only displayed fields. diff --git a/guides/advanced_guides/filtering.md b/reference/features/filtering.md similarity index 98% rename from guides/advanced_guides/filtering.md rename to reference/features/filtering.md index 2528b830af..694fab84f9 100644 --- a/guides/advanced_guides/filtering.md +++ b/reference/features/filtering.md @@ -6,7 +6,7 @@ Meilisearch allows you to define filters thanks to a **very simple query languag ### Using Filters -In order to apply filtering to a search, simply add a filter expression to the `filters` query parameter of your search. Find out more on search query parameters in our [API reference](https://docs.meilisearch.com/references/search.html#query-parameters). +In order to apply filtering to a search, simply add a filter expression to the `filters` query parameter of your search. Find out more on search query parameters in our [API reference](/reference/api/search.md#query-parameters). ### The Query Language diff --git a/guides/advanced_guides/installation.md b/reference/features/installation.md similarity index 86% rename from guides/advanced_guides/installation.md rename to reference/features/installation.md index dc5b214ebb..7721aeb64d 100644 --- a/guides/advanced_guides/installation.md +++ b/reference/features/installation.md @@ -100,21 +100,21 @@ $ ./meilisearch --db-path ./meilifiles --http-addr '127.0.0.1:7700' Server is listening on: http://127.0.0.1:7700 ``` -Here is the list of [all the options and how to use them](/guides/advanced_guides/configuration.md). +Here is the list of [all the options and how to use them](/reference/features/configuration.md). ## Updating MeiliSearch -Getting the latest version of MeiliSearch is a straightforward process: simply fetch and install the latest binary with your preferred method (see [installation](/guides/advanced_guides/installation.md#download-and-launch) above). +Getting the latest version of MeiliSearch is a straightforward process: simply fetch and install the latest binary with your preferred method (see [installation](/reference/features/installation.md#download-and-launch) above). However, please note that prior to our official release (`v1.0`), all minor updates (`v0.X`) are considered breaking. Therefore, **MeiliSearch databases are not compatible across versions** for as long as we are in beta. -If you want to transfer your database from an outdated MeiliSearch instance to the most recent version, we recommend following [the below guide](/guides/advanced_guides/installation.md#migrating-a-database-to-a-later-version). +If you want to transfer your database from an outdated MeiliSearch instance to the most recent version, we recommend following [the below guide](/reference/features/installation.md#migrating-a-database-to-a-later-version). If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, simply delete your database folder (defaults to `data.ms`), and re-index all your documents. ### Migrating a Database to a Later Version -Using [dumps](/guides/advanced_guides/snapshots_and_dumps.md#dumps), you can export your MeiliSearch data—all indexes, documents, and settings contained in your database—into a transferrable state. Then, you can re-import this data after updating MeiliSearch to the latest version. +Using [dumps](/reference/features/dumps.md), you can export your MeiliSearch data—all indexes, documents, and settings contained in your database—into a transferrable state. Then, you can re-import this data after updating MeiliSearch to the latest version. Since the content is exported in a way that guarantees mobility, it needs to be re-indexed. If your database is large, this process can take a long time. Nonetheless, this process guarantees **to migrate all settings and documents between two different versions of MeiliSearch**. diff --git a/guides/advanced_guides/known_limitations.md b/reference/features/known_limitations.md similarity index 90% rename from guides/advanced_guides/known_limitations.md rename to reference/features/known_limitations.md index e61b9feaa3..1d2f54ff4c 100644 --- a/guides/advanced_guides/known_limitations.md +++ b/reference/features/known_limitations.md @@ -11,7 +11,7 @@ Some of these limitations have been made by MeiliSearch developers for relevacy MeiliSearch uses two databases: the first one for storage and the second one for updates. On launch LMDB needs to know the size that it can allocate on disk. This space will be reserved on disk for LMDB, thus MeiliSearch. This space will also be allocated as virtual memory. -The maxime database size is by default __100GiB__ for each databases. This size can me modified using the options `--max-mdb-size` & `--max-udb-size` as described in the [configuration guide](/guides/advanced_guides/configuration.md#max-mdb-size). +The maxime database size is by default __100GiB__ for each databases. This size can me modified using the options `--max-mdb-size` & `--max-udb-size` as described in the [configuration guide](/reference/features/configuration.md#max-mdb-size). ### Number of indexes @@ -27,4 +27,4 @@ This limit is enforced for relevancy reasons. The more words there are in a give ### Payload size -The default limit for the payload size is around __100MB__. [This limit can be modified](/guides/advanced_guides/configuration.md#payload-limit-size). +The default limit for the payload size is around __100MB__. [This limit can be modified](/reference/features/configuration.md#payload-limit-size). diff --git a/guides/advanced_guides/search_parameters.md b/reference/features/search_parameters.md similarity index 76% rename from guides/advanced_guides/search_parameters.md rename to reference/features/search_parameters.md index 760224155f..e1b63f4d2c 100644 --- a/guides/advanced_guides/search_parameters.md +++ b/reference/features/search_parameters.md @@ -4,25 +4,25 @@ Search parameters let the user customize their search request. | Query Parameter | Description | Default Value | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | :-----------: | -| **[q](/guides/advanced_guides/search_parameters.md#query-q)** | Query string | `""` | -| **[offset](/guides/advanced_guides/search_parameters.md#offset)** | Number of documents to skip | `0` | -| **[limit](/guides/advanced_guides/search_parameters.md#limit)** | Maximum number of documents returned | `20` | -| **[filters](/guides/advanced_guides/search_parameters.md#filters)** | Filter queries by an attribute value | `null` | -| **[facetFilters](/guides/advanced_guides/search_parameters.md#facet-filters)** | Facet names and values to filter on | `null` | -| **[facetsDistribution](/guides/advanced_guides/search_parameters.md#the-facets-distribution)** | Facets for which to retrieve the matching count | `null` | -| **[attributesToRetrieve](/guides/advanced_guides/search_parameters.md#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | -| **[attributesToCrop](/guides/advanced_guides/search_parameters.md#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | -| **[cropLength](/guides/advanced_guides/search_parameters.md#crop-length)** | Length used to crop field values | `200` | -| **[attributesToHighlight](/guides/advanced_guides/search_parameters.md#attributes-to-highlight)** | Attributes whose values will contain highlighted matching terms | `null` | -| **[matches](/guides/advanced_guides/search_parameters.md#matches)** | Defines whether an object that contains information about the matches should be returned or not | `false` | +| **[q](/reference/features/search_parameters.md#query-q)** | Query string | `""` | +| **[offset](/reference/features/search_parameters.md#offset)** | Number of documents to skip | `0` | +| **[limit](/reference/features/search_parameters.md#limit)** | Maximum number of documents returned | `20` | +| **[filters](/reference/features/search_parameters.md#filters)** | Filter queries by an attribute value | `null` | +| **[facetFilters](/reference/features/search_parameters.md#facet-filters)** | Facet names and values to filter on | `null` | +| **[facetsDistribution](/reference/features/search_parameters.md#the-facets-distribution)** | Facets for which to retrieve the matching count | `null` | +| **[attributesToRetrieve](/reference/features/search_parameters.md#attributes-to-retrieve)** | Attributes to display in the returned documents | `["*"]` | +| **[attributesToCrop](/reference/features/search_parameters.md#attributes-to-crop)** | Attributes whose values have to be cropped | `null` | +| **[cropLength](/reference/features/search_parameters.md#crop-length)** | Length used to crop field values | `200` | +| **[attributesToHighlight](/reference/features/search_parameters.md#attributes-to-highlight)** | Attributes whose values will contain highlighted matching terms | `null` | +| **[matches](/reference/features/search_parameters.md#matches)** | Defines whether an object that contains information about the matches should be returned or not | `false` | ## Query (q) This is the string used by the search engine to find relevant documents. When `q` isn't specified, a placeholder search is performed, returning documents that best match other search parameters. -A placeholder allows you to find documents without providing search terms. It will return documents sorted according to the [ranking rules](/guides/advanced_guides/settings.md#ranking-rules) order. -It also supports [faceting](/guides/advanced_guides/faceted_search.md) and [filtering](/guides/advanced_guides/filtering.md) +A placeholder allows you to find documents without providing search terms. It will return documents sorted according to the [ranking rules](/reference/features/settings.md#ranking-rules) order. +It also supports [faceting](/reference/features/faceted_search.md) and [filtering](/reference/features/filtering.md) `q=` @@ -76,7 +76,7 @@ If you want to get only **two** documents, set `limit` to `2`. `filters=` -Specify a filter to be used with the query. See our [dedicated guide](/guides/advanced_guides/filtering.md). +Specify a filter to be used with the query. See our [dedicated guide](/reference/features/filtering.md). @@ -96,7 +96,7 @@ The parameter should be **URL-encoded**. ## Facet filters -If you have [set up faceted attributes](/guides/advanced_guides/settings.md#attributes-for-faceting), you can filter on [facets](/guides/advanced_guides/faceted_search.md) to narrow down your results based on criteria. +If you have [set up faceted attributes](/reference/features/settings.md#attributes-for-faceting), you can filter on [facets](/reference/features/faceted_search.md) to narrow down your results based on criteria. `facetFilters=["facetName:facetValue"]` or `facetFilters=[["facetName:facetValue"]]` or a mix of both `facetFilters=["facetName1:facetValue1", ["facetName2:facetValue2"]]` @@ -109,13 +109,13 @@ or a mix of both `facetFilters=["facetName1:facetValue1", ["facetName2:facetValu - `facetName`: The name (the attribute) of a field used as a facet (e.g. `director`, `genres`). - `facetValue`: The value of this facet to filter results on (e.g. `Tim Burton`, `Mati Diop`, `Comedy`, `Romance`). -Facet filters also support logical connectives by using [inner and outer array elements](/guides/advanced_guides/faceted_search.md#using-facets). +Facet filters also support logical connectives by using [inner and outer array elements](/reference/features/faceted_search.md#using-facets). -[Learn more about facet filters in the dedicated guide](/guides/advanced_guides/faceted_search.md) +[Learn more about facet filters in the dedicated guide](/reference/features/faceted_search.md) #### Example -Suppose you have declared `director` and `genres` as [faceted attributes](/guides/advanced_guides/settings.md#attributes-for-faceting), and you want to get movies matching "thriller" classified as either horror **or** mystery **and** directed by Jordan Peele. +Suppose you have declared `director` and `genres` as [faceted attributes](/reference/features/settings.md#attributes-for-faceting), and you want to get movies matching "thriller" classified as either horror **or** mystery **and** directed by Jordan Peele. ```SQL ("genres:Horror" OR "genres:Mystery") AND "director:Jordan Peele" @@ -161,7 +161,7 @@ And you would get the following response: ## The facets distribution -If you have [set up faceted attributes](/guides/advanced_guides/settings.md#attributes-for-faceting), you can retrieve the count of matching terms for each [facets](/guides/advanced_guides/faceted_search.md). +If you have [set up faceted attributes](/reference/features/settings.md#attributes-for-faceting), you can retrieve the count of matching terms for each [facets](/reference/features/faceted_search.md). `facetsDistribution=[, , ...]` @@ -187,7 +187,7 @@ If the `facetsDistribution` parameter has been set, the returned results will co Otherwise, returns `false` if this count is **approximative** (approximative count for each facet value). The approximative facet count happens when there are too many documents in too many different facet values. In which case, MeiliSearch stops the distribution count to prevent considerably slowing down the request. -[Learn more about facet distribution in the dedicated guide](/guides/advanced_guides/faceted_search.md#the-facets-distribution) +[Learn more about facet distribution in the dedicated guide](/reference/features/faceted_search.md#the-facets-distribution) #### Example @@ -230,7 +230,7 @@ Attributes to **display** in the returned documents. Comma-separated list of attributes whose fields will be present in the returned documents. - Defaults to to the [displayedAttributes list](/guides/advanced_guides/settings.md#displayed-attributes) which contains by default all attributes found in the documents. + Defaults to to the [displayedAttributes list](/reference/features/settings.md#displayed-attributes) which contains by default all attributes found in the documents. #### Example @@ -249,13 +249,13 @@ Attribute can have two values: - `` OR `` (Optional, string, defaults to empty) Comma-separated list of attributes whose values will be cropped if they contain a matched query word. - Each attribute can be joined by an optional `cropLength` that overwrites the [cropLength](/guides/advanced_guides/search_parameters.md#crop-length) parameter. + Each attribute can be joined by an optional `cropLength` that overwrites the [cropLength](/reference/features/search_parameters.md#crop-length) parameter. - `['*']` In this case, all the attributes present in `attributesToRetrieve` will be assigned to `attributesToCrop`. -In the case a matched query word is found, the field's value will be cropped around the first matched query word according to the `cropLength` value (default `200` see [cropLength](/guides/advanced_guides/search_parameters.md#crop-length) to change this value). +In the case a matched query word is found, the field's value will be cropped around the first matched query word according to the `cropLength` value (default `200` see [cropLength](/reference/features/search_parameters.md#crop-length) to change this value). Some working examples: @@ -298,7 +298,7 @@ You will get the following response with the **cropped version in the \_formatte `cropLength=` (Optional, positive integer, defaults to `200`) -Number of characters to keep on each side of the start of the matching word. See [attributesToCrop](/guides/advanced_guides/search_parameters.md#attributes-to-crop). +Number of characters to keep on each side of the start of the matching word. See [attributesToCrop](/reference/features/search_parameters.md#attributes-to-crop). ## Attributes to Highlight @@ -395,3 +395,15 @@ You will get the following response with the **information about the matches in } } ``` + +## Examples + +Here are a few examples of what can be achieved with search parameters: + +Results can be paginated using the `limit` and `offset` query parameters. + + + +You can filter results using the `filters` query parameter. + + diff --git a/guides/advanced_guides/settings.md b/reference/features/settings.md similarity index 74% rename from guides/advanced_guides/settings.md rename to reference/features/settings.md index 2c2609a754..3744bb1026 100644 --- a/guides/advanced_guides/settings.md +++ b/reference/features/settings.md @@ -4,13 +4,13 @@ This page describes all the **settings** available in MeiliSearch and how to **c | Variable | Description | Default value | | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| **[synonyms](/guides/advanced_guides/settings.md#synonyms)** | List of associated words treated similarly | `{}` | -| **[stopWords](/guides/advanced_guides/settings.md#stop-words)** | List of words ignored by MeiliSearch when present in search queries | `[]` | -| **[attributesForFaceting](/guides/advanced_guides/settings.md#attributes-for-faceting)** | Attributes to use as facets | `null` | -| **[rankingRules](/guides/advanced_guides/settings.md#ranking-rules)** | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/guides/main_concepts/relevancy.md#order-of-the-rules) | -| **[distinctAttribute](/guides/advanced_guides/settings.md#distinct-attribute)** | Search returns documents with distinct (different) values of the given field | `null` | -| **[searchableAttributes](/guides/advanced_guides/settings.md#searchable-attributes)** | Fields in which to search for matching query words sorted by order of importance | All attributes found in the documents | -| **[displayedAttributes](/guides/advanced_guides/settings.md#displayed-attributes)** | Fields displayed in the returned documents | All attributes found in the documents | +| **[synonyms](/reference/features/settings.md#synonyms)** | List of associated words treated similarly | `{}` | +| **[stopWords](/reference/features/settings.md#stop-words)** | List of words ignored by MeiliSearch when present in search queries | `[]` | +| **[attributesForFaceting](/reference/features/settings.md#attributes-for-faceting)** | Attributes to use as facets | `null` | +| **[rankingRules](/reference/features/settings.md#ranking-rules)** | List of ranking rules sorted by order of importance | [A list of ordered built-in ranking rules](/learn/core_concepts/relevancy.md#order-of-the-rules) | +| **[distinctAttribute](/reference/features/settings.md#distinct-attribute)** | Search returns documents with distinct (different) values of the given field | `null` | +| **[searchableAttributes](/reference/features/settings.md#searchable-attributes)** | Fields in which to search for matching query words sorted by order of importance | All attributes found in the documents | +| **[displayedAttributes](/reference/features/settings.md#displayed-attributes)** | Fields displayed in the returned documents | All attributes found in the documents | ## Synonyms @@ -22,7 +22,7 @@ A set of words defined for an index. Synonyms are **different words that have th An object that contains words with a list of their associated synonyms. -[Learn more about synonyms](/guides/advanced_guides/synonyms.md) +[Learn more about synonyms](/reference/features/synonyms.md) #### Example @@ -42,7 +42,7 @@ A set of words defined for an index. Because some words neither add semantic val An array of strings that contains the stop words. -[Learn more about stop words](/guides/advanced_guides/stop_words.md) +[Learn more about stop words](/reference/features/stop_words.md) #### Example @@ -56,7 +56,7 @@ Suppose you would like to search `the mask` in a movie database. Since `the` is ## Attributes For Faceting -Faceted are the attributes used as facets. They **must be added to the settings to be usable as [facet filters](/guides/advanced_guides/search_parameters.md#facet-filters)**. +Faceted are the attributes used as facets. They **must be added to the settings to be usable as [facet filters](/reference/features/search_parameters.md#facet-filters)**. `attributesForFaceting=[, ...]` @@ -69,7 +69,7 @@ Faceted are the attributes A `null` value will be ignored. In any other case, an error will be thrown. ::: -[Learn more about faceted attributes](/guides/advanced_guides/faceted_search.md) +[Learn more about faceted attributes](/reference/features/faceted_search.md) #### Example @@ -93,7 +93,7 @@ Default value (the ranking rules in the default order): ["typo", "words", "proximity", "attribute", "wordsPosition", "exactness"] ``` -[Read this guide to know more about what each ranking rules does](/guides/main_concepts/relevancy.md) +[Read this guide to know more about what each ranking rules does](/learn/core_concepts/relevancy.md) ### Custom ranking rule @@ -117,7 +117,7 @@ The **value of a field** whose attribute is set as a distinct attribute will alw The field name. -[Learn more about the distinct attribute](/guides/advanced_guides/distinct.md) +[Learn more about the distinct attribute](/reference/features/distinct.md) #### Example @@ -152,7 +152,7 @@ With the settings in the example above, only one of the two documents will be re ## Searchable attributes -The content of the fields whose attributes are added to the [searchable-attributes list](/references/searchable_attributes.md) are **searched for matching query words**. +The content of the fields whose attributes are added to the [searchable-attributes list](/reference/api/searchable_attributes.md) are **searched for matching query words**. `searchableAttributes=[, , ...]` @@ -160,7 +160,7 @@ The content of the fields whose attributes are added to the [searchable-attribut An array of strings that contains searchable attributes ordered by importance (arranged from the most important attribute to the least important attribute). -[Learn more about searchable attributes](/guides/advanced_guides/field_properties.md#searchable-fields) +[Learn more about searchable attributes](/reference/features/field_properties.md#searchable-fields) #### Example @@ -170,7 +170,7 @@ By adding the following settings, the fields `title`, `description` and `genre` ## Displayed attributes -The fields whose attributes are added to the [displayed-attributes list](/references/displayed_attributes.md) are **contained in each matching document**. +The fields whose attributes are added to the [displayed-attributes list](/reference/features/field_properties.md) are **contained in each matching document**. Documents returned upon search contain only displayed fields. @@ -180,7 +180,7 @@ Documents returned upon search contain only displayed fields. An array of strings that contains attributes of an index to display. -[Learn more about displayed attributes](/guides/advanced_guides/field_properties.md#displayed-fields) +[Learn more about displayed attributes](/reference/features/field_properties.md#displayed-fields) #### Example diff --git a/reference/features/snapshots.md b/reference/features/snapshots.md new file mode 100644 index 0000000000..03a861f9f8 --- /dev/null +++ b/reference/features/snapshots.md @@ -0,0 +1,73 @@ +# Snapshots + +A snapshot is an exact copy of the database (i.e. the data.ms folder) at the time the snapshot was created. Besides compression, snapshots do not go through any processing. They can be thought of as "pre-compiled copies". + +Using this feature, it is possible to schedule snapshot creation at custom intervals and use existing snapshots to restore MeiliSearch. + +## Creating Snapshots + +For MeiliSearch to create snapshots, the feature must be enabled by adding the following flag: + +```bash +$ meilisearch --schedule-snapshot=true +``` + +By default, MeiliSearch creates snapshots in a directory called `snapshots/` at the root of your MeiliSearch. + +The destination can be modified with the `--snapshot-dir` flag. + +```bash +$ meilisearch --schedule-snapshot=true --snapshot-dir mySnapShots/ +``` + +Now snapshots are created in `mySnapShots/` directory. + +The first snapshot is created on launching MeiliSearch. After that, snapshots are created routinely on a set interval until you deactivate snapshots or end the MeiliSearch instance. By default, one snapshot is taken every 24 hours. + +The amount of time between each new snapshot can be modified with the `--snapshot-interval-sec` flag. + +```bash +$ meilisearch --schedule-snapshot=true --snapshot-interval-sec 3600 +``` + +After running the above code, a snapshot is created every hour (3600 seconds). + +During snapshot creation, old snapshots are **automatically overwritten**. This means that only the most recent snapshot should be present in the folder at any given time. + +[[More about snapshots flags and env variables]](/reference/features/configuration.md#schedule-snapshot-creation) + +## Starting from a Snapshot + +Because snapshots are exact copies of your database that haven't gone through any processing besides compression, starting a MeiliSearch instance from a snapshot is significantly faster than adding documents manually or starting from a dump. + +Using the global environment `MEILI_IMPORT_SNAPSHOT` or the CLI flag `--import-snapshot` , MeiliSearch will start the server using the provided snapshot. + +```bash +$ meilisearch --import-snapshot mySnapShots/data.ms.snapshot +``` + +## Common Problems + +Take note that whenever you launch MeiliSearch from a snapshot, it will *stop processing and throw an error** if it encounters either of the two following situations: + +1. A database already exists (i.e. you have a non-empty `data.ms` folder in the same directory as your MeiliSearch binary) +2. No snapshot is found at the given path + +In both cases, **this behavior is [configurable](/reference/features/configuration.md#ignore-missing-snapshot)**. + +If you don't want MeiliSearch to throw an error when finding that a database already exists, you can add the following flag: `--ignore-snapshot-if-db-exists=true`. When using this flag, MeiliSearch will use the existing database to start an instance instead of throwing an error. The snapshot will be ignored. + +If you do not want MeiliSearch to throw an error when there is no snapshot at the given path, you can add the following flag: `--ignore-missing-snapshot`. MeiliSearch will then continue its process and not import any snapshot. + +When starting from a snapshot, chances are that you already have an existing database. **For security reasons, a database is never overwritten**. To load a snapshot when an existing database is present, you will have to manually delete the existing database. By default, this is the contents of the `data.ms` folder (unless you [changed the path](/reference/features/configuration.md#database-path)) which is located in the same folder as your MeiliSearch binary. +The simplest way to delete your database is with the terminal command `rm -rf data.ms`, after which you should be able to start MeiliSearch with a snapshot. + +[[More about snapshots flags and env variables]](/reference/features/configuration.md#schedule-snapshot-creation) + +## Use Cases + +**Snapshots are safeguards in case of problems**. If your MeiliSearch instance encounters a problem or if you make a mistake while manipulating your database, restarting your instance with the latest snapshot is an easy way to recover your data. + +### Version Compatibility + +Since a snapshot is an exact replica of your database, it can only be opened by the same version of MeiliSearch that created it. diff --git a/guides/advanced_guides/stop_words.md b/reference/features/stop_words.md similarity index 100% rename from guides/advanced_guides/stop_words.md rename to reference/features/stop_words.md diff --git a/guides/advanced_guides/synonyms.md b/reference/features/synonyms.md similarity index 91% rename from guides/advanced_guides/synonyms.md rename to reference/features/synonyms.md index 1573d6c95c..5c40850639 100644 --- a/guides/advanced_guides/synonyms.md +++ b/reference/features/synonyms.md @@ -1,6 +1,6 @@ # Synonyms -To make your search more relevant, you can [create a list of synonyms](/references/synonyms.md#update-synonyms). +To make your search more relevant, you can [create a list of synonyms](/reference/api/synonyms.md#update-synonyms). If multiples words have an equivalent meaning in your dataset, you can decide to create a synonym list for these words. The search engine will give the same search results for any search with one of the associated words as a query. @@ -27,7 +27,7 @@ By searching `phone` you will get all results containing `iphone` with the same #### Example -To create a one-way synonym list this is the JSON that should be [added to the settings](/references/synonyms.md#update-synonyms). +To create a one-way synonym list this is the JSON that should be [added to the settings](/reference/api/synonyms.md#update-synonyms). ```json { @@ -59,7 +59,7 @@ The "San Fransisco" search will be considered less relevant than the "SF" search #### Example -To create a multi-way synonym list this is the JSON that should be [added to the settings](/references/synonyms.md#update-synonyms). +To create a multi-way synonym list this is the JSON that should be [added to the settings](/reference/api/synonyms.md#update-synonyms). ```json { diff --git a/guides/advanced_guides/web_interface.md b/reference/features/web_interface.md similarity index 64% rename from guides/advanced_guides/web_interface.md rename to reference/features/web_interface.md index 6ab7c6fbca..504aaddbbd 100644 --- a/guides/advanced_guides/web_interface.md +++ b/reference/features/web_interface.md @@ -1,11 +1,11 @@ # Web interface -After adding documents to your MeiliSearch, it is possible to try out the search engine with the integrated web interface. This only works in a [development environment](/guides/advanced_guides/configuration.md#environment). +After adding documents to your MeiliSearch, it is possible to try out the search engine with the integrated web interface. This only works in a [development environment](/reference/features/configuration.md#environment). -The web interface is served on the address and port specified in the command line argument `--listen`. If not specified, [the default address and port is used](/guides/advanced_guides/configuration.md#http-address-port-binding). +The web interface is served on the address and port specified in the command line argument `--listen`. If not specified, [the default address and port is used](/reference/features/configuration.md#http-address-port-binding). ::: warning -Since the production environment requires an API-key for searching, the web interface is only available in [development mode](/guides/advanced_guides/configuration.md#environment). +Since the production environment requires an API-key for searching, the web interface is only available in [development mode](/reference/features/configuration.md#environment). ::: ### Example diff --git a/reference/under_the_hood/README.md b/reference/under_the_hood/README.md new file mode 100644 index 0000000000..201308fabf --- /dev/null +++ b/reference/under_the_hood/README.md @@ -0,0 +1,17 @@ +# Under the Hood + +This section explores how MeiliSearch works under the hood. + +This information is not necessary to set up MeiliSearch, but it may help you master some of the intricacies of our engine, or make your own contribution to MeiliSearch. + +## Table of Contents + +To better understand some of the algorithms behind our beloved search engine, check out the following reference articles: + +[Bucket Sort](/reference/under_the_hood/bucket_sort.md) +[Concatenate and Split Queries](/reference/under_the_hood/concat.md) +[Data Types](/reference/under_the_hood/datatypes.md) +[Prefix Search](/reference/under_the_hood/prefix.md) +[Storage](/reference/under_the_hood/storage.md) +[Tokenization](/reference/under_the_hood/tokenization.md) +[Typo Tolerance](/reference/under_the_hood/typotolerance.md) diff --git a/guides/advanced_guides/bucket_sort.md b/reference/under_the_hood/bucket_sort.md similarity index 88% rename from guides/advanced_guides/bucket_sort.md rename to reference/under_the_hood/bucket_sort.md index 2586533f2e..f032afc472 100644 --- a/guides/advanced_guides/bucket_sort.md +++ b/reference/under_the_hood/bucket_sort.md @@ -4,4 +4,4 @@ A [bucket sort](https://en.wikipedia.org/wiki/Bucket_sort) can be described as a All the documents are sorted within the first `criterion`, then documents that can not be distinguished will be sorted using the second criterion, and so on. Thus, all documents are not sorted for every criterion, which induces a reduced compute time. -[Here is the ordered list of the default criteria used in MeiliSearch.](/guides/main_concepts/relevancy.md#ranking-rules) +[Here is the ordered list of the default criteria used in MeiliSearch.](/learn/core_concepts/relevancy.md#ranking-rules) diff --git a/guides/advanced_guides/concat.md b/reference/under_the_hood/concat.md similarity index 100% rename from guides/advanced_guides/concat.md rename to reference/under_the_hood/concat.md diff --git a/guides/advanced_guides/datatypes.md b/reference/under_the_hood/datatypes.md similarity index 80% rename from guides/advanced_guides/datatypes.md rename to reference/under_the_hood/datatypes.md index ba162f97b5..590736e0b9 100644 --- a/guides/advanced_guides/datatypes.md +++ b/reference/under_the_hood/datatypes.md @@ -9,12 +9,12 @@ Based on their type, however, the fields will be handled and used in different w Types: -- [String](/guides/advanced_guides/datatypes.md#string) -- [Numeric types](/guides/advanced_guides/datatypes.md#numeric-type): `integer`, `float` -- [Boolean](/guides/advanced_guides/datatypes.md#boolean) -- [Array](/guides/advanced_guides/datatypes.md#array) -- [Object](/guides/advanced_guides/datatypes.md#object) -- [`null` type](/guides/advanced_guides/datatypes.md#null-type) +- [String](/reference/under_the_hood/datatypes.md#string) +- [Numeric types](/reference/under_the_hood/datatypes.md#numeric-type): `integer`, `float` +- [Boolean](/reference/under_the_hood/datatypes.md#boolean) +- [Array](/reference/under_the_hood/datatypes.md#array) +- [Object](/reference/under_the_hood/datatypes.md#object) +- [`null` type](/reference/under_the_hood/datatypes.md#null-type) ### String @@ -32,7 +32,7 @@ For Latin-based languages, there are two kinds of **space separators**: - **Soft spaces** (distance: 1): whitespaces, quotes, `'-' | '_' | '\'' | ':' | '/' | '\\' | '@'` - **Hard spaces** (distance: 8): `'.' | ';' | ',' | '!' | '?' | '(' | ')'` -Distance plays an essential role in determining whether documents are relevant since [one of the ranking rules is the **proximity** rule](/guides/main_concepts/relevancy.md). The proximity rule sorts the results by increasing distance between matched query terms. Then, two words separated by a soft space are closer and thus considered **more relevant** than two words separated by a hard space. +Distance plays an essential role in determining whether documents are relevant since [one of the ranking rules is the **proximity** rule](/learn/core_concepts/relevancy.md). The proximity rule sorts the results by increasing distance between matched query terms. Then, two words separated by a soft space are closer and thus considered **more relevant** than two words separated by a hard space. After the tokenizing process, each word is indexed and stored in the global dictionary of the corresponding index. @@ -69,8 +69,8 @@ This will happen because the proximity distance between `Bruce` and `Willis` is A numeric type (`integer`, `float`) is converted to a human-readable decimal number string representation. Numeric types can be searched as they are converted to strings. -You can [add custom ranking rules](/guides/main_concepts/relevancy.md#adding-your-rules) to create an ascending or descending sorting rule on a given attribute that has a numeric value in the documents. -You can also create [filters](/guides/advanced_guides/filtering.md). The `>`, `>=`, `<`, and `<=` relational operators apply only to numerical values. +You can [add custom ranking rules](/learn/core_concepts/relevancy.md#adding-your-rules) to create an ascending or descending sorting rule on a given attribute that has a numeric value in the documents. +You can also create [filters](/reference/features/filtering.md). The `>`, `>=`, `<`, and `<=` relational operators apply only to numerical values. ### Boolean @@ -96,7 +96,7 @@ Will be processed as if all elements were arranged at the same level: "Bruce Willis. Vin Diesel. Kung Fu Panda." ``` -The strings above will be separated by soft and hard spaces exactly as explained in the [string example](/guides/advanced_guides/datatypes.md#examples). +The strings above will be separated by soft and hard spaces exactly as explained in the [string example](/reference/under_the_hood/datatypes.md#examples). ### Object @@ -119,7 +119,7 @@ In the example above, `movie_id`, `1564saqw12ss`, `title`, `Kung fu Panda` are a "movie_id. 1564saqw12ss. title. Kung fu Panda." ``` -These sentences will be separated by soft and hard spaces exactly as explained in the [string example](/guides/advanced_guides/datatypes.md#examples). +These sentences will be separated by soft and hard spaces exactly as explained in the [string example](/reference/under_the_hood/datatypes.md#examples). ### null type diff --git a/guides/advanced_guides/prefix.md b/reference/under_the_hood/prefix.md similarity index 76% rename from guides/advanced_guides/prefix.md rename to reference/under_the_hood/prefix.md index 588523e960..6e98ba9658 100644 --- a/guides/advanced_guides/prefix.md +++ b/reference/under_the_hood/prefix.md @@ -4,7 +4,7 @@ In MeiliSearch, **the search is possible even with a single letter sent**. A prefix search is when the documents sorting starts by comparing your search query with the start of each word in your dataset. -All words beginning with this letter are added to the [bucket sort](/guides/advanced_guides/bucket_sort.md), and then the other [ranking rules](/guides/main_concepts/relevancy.md) are applied. +All words beginning with this letter are added to the [bucket sort](/reference/under_the_hood/bucket_sort.md), and then the other [ranking rules](/learn/core_concepts/relevancy.md) are applied. ::: note Searching by prefix has a significant impact on search time. The shorter the word, the more possible matches in the documents increase. @@ -34,8 +34,8 @@ response: Notice that a prefix search is only done for the last word of a query, other words must be of the same length but can contain typos. -MeiliSearch also handles typos while performing the prefix search. You can [read more about the typo rules on the dedicated page](/guides/advanced_guides/typotolerance.md#typo-tolerance-rules). +MeiliSearch also handles typos while performing the prefix search. You can [read more about the typo rules on the dedicated page](/reference/under_the_hood/typotolerance.md#typo-tolerance-rules). ::: tip -We also [apply splitting and concatenating on search queries](/guides/advanced_guides/concat.md). +We also [apply splitting and concatenating on search queries](/reference/under_the_hood/concat.md). ::: diff --git a/resources/about_storage.md b/reference/under_the_hood/storage.md similarity index 98% rename from resources/about_storage.md rename to reference/under_the_hood/storage.md index 13fc060f1a..0bcf593abe 100644 --- a/resources/about_storage.md +++ b/reference/under_the_hood/storage.md @@ -1,4 +1,4 @@ -# About storage +# Storage ::: tip TLDR @@ -51,7 +51,7 @@ In this case, MeiliSearch will always ask for a memory map of 200Gb. This refers ## Measured disk usage -We did some measurements on the default [movies.json](https://github.com/meilisearch/MeiliSearch/blob/master/datasets/movies/movies.json) dataset that you can find in the [getting started guide](/guides/introduction/quick_start_guide.md#add-documents). +We did some measurements on the default [movies.json](https://github.com/meilisearch/MeiliSearch/blob/master/datasets/movies/movies.json) dataset that you can find in the [getting started guide](/learn/tutorials/getting_started.md#add-documents). This dataset is a JSON file of 8.6 MB and has 19,553 documents. When we index this file in MeiliSearch, the amount of disk space taken by LMDB is 122MB. diff --git a/reference/under_the_hood/tokenization.md b/reference/under_the_hood/tokenization.md new file mode 100644 index 0000000000..abc0421d38 --- /dev/null +++ b/reference/under_the_hood/tokenization.md @@ -0,0 +1,25 @@ +# Tokenization + +**Tokenization** is the act of taking a sentence or phrase and splitting it into smaller units of language, called tokens. It is the first step of document indexing in the Meilisearch engine, and is a critical factor in the quality of search results. + +Breaking sentences into smaller chunks requires understanding where one word ends and another begins, making tokenization a highly complex and language-dependant task. MeiliSearch's solution to this problem is a **modular tokenizer** that follows different processes, called **pipelines**, based on the language it detects. + +This allows MeiliSearch to function in several different languages with zero setup. + +## Deep Dive: The Meili Tokenizer + +![Tokenizer Architecture](https://user-images.githubusercontent.com/6482087/102896344-8560d200-4466-11eb-8cfe-b4ae8741093b.jpg) + +When you add documents to a MeiliSearch index, the tokenization process is handled by an abstract interface called an **analyzer**. The analyzer is responsible for determining the primary language of each based on the scripts (e.g. Latin alphabet, Chinese hanzi, etc.) that are present there. Then, it applies the corresponding **pipeline** to each field. + +We can break down the tokenization process like so: + +1. Crawl the document(s) and determine the primary language for each field. +2. Go back over the documents field-by-field, running the corresponding tokenization pipeline, if it exists. + +Pipelines include many language-specific operations. Currently, we have two pipelines: + +1. A specialized Chinese pipeline using [Jieba](https://github.com/messense/jieba-rs) +2. A default MeiliSearch pipeline that separates words based on categories. Works with a variety of languages. + +For more details, check out the [feature specification](https://github.com/meilisearch/specifications/blob/master/text/0001-script-based-tokenizer.md). diff --git a/guides/advanced_guides/typotolerance.md b/reference/under_the_hood/typotolerance.md similarity index 92% rename from guides/advanced_guides/typotolerance.md rename to reference/under_the_hood/typotolerance.md index 5b41bc4efa..768aef0c76 100644 --- a/guides/advanced_guides/typotolerance.md +++ b/reference/under_the_hood/typotolerance.md @@ -1,6 +1,6 @@ # Typo Tolerance -MeiliSearch **is [typo tolerant](/guides/advanced_guides/typotolerance.md#typo-tolerance-rules)**; this means **it understands your search even if there are typos or spelling mistakes** to a certain extend. +MeiliSearch **is [typo tolerant](/reference/under_the_hood/typotolerance.md#typo-tolerance-rules)**; this means **it understands your search even if there are typos or spelling mistakes** to a certain extend. #### Example diff --git a/resources/README.md b/resources/README.md deleted file mode 100644 index b5d7ed77dc..0000000000 --- a/resources/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Resources - -This section offers resources to expand your knowledge of MeiliSearch. - -Content: - -- [SDKs](/resources/sdks.md) -- [About storage](/resources/about_storage.md) -- [Comparison to alternatives](/resources/comparison_to_alternatives.md) -- [Postman collection for MeiliSearch API](/resources/postman_collection.md) diff --git a/resources/howtos/README.md b/resources/howtos/README.md deleted file mode 100644 index 6a6dcb726e..0000000000 --- a/resources/howtos/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# How To's - -How-to guides take the reader through the steps required to solve a real-world problem. - -### Available content - -- [How to implement Instant Search within 5 minutes in your React App!](/resources/howtos/meilisearch_react.md) - Learn how to create an instant search in react using MeiliSearch. -- [How to deploy a MeiliSearch instance on DigitalOcean](/resources/howtos/digitalocean_droplet.md) - Learn how to launch a MeiliSearch instance hosted in a DigitalOcean server. -- [How to integrate a relevant search bar to your docs](/resources/howtos/search_bar_for_docs.md) -- [How to use HTTP2 and SSL](/resources/howtos/http2_ssl.md) diff --git a/resources/tutorials/README.md b/resources/tutorials/README.md deleted file mode 100644 index e5690af18c..0000000000 --- a/resources/tutorials/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# Tutorials - -The tutorials will bring you from A to Z explaining each step thoroughly. - -### Available content - -- [MeiliSearch in production: taking it to the next level](/resources/tutorials/running_production.md) - Learn how to deploy MeiliSearch in production on a server.