From 5c36fb44512201c0ccf69e0726a5154a2a9ea418 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Tue, 23 Feb 2021 18:25:20 -0500 Subject: [PATCH 01/16] Rework how-to sidebar --- .vuepress/config.js | 59 ++++++++++++++----- create/how_to/installation.md | 0 create/how_to/updating.md | 107 ++++++++++++++++++++++++++++++++++ 3 files changed, 153 insertions(+), 13 deletions(-) create mode 100644 create/how_to/installation.md create mode 100644 create/how_to/updating.md diff --git a/.vuepress/config.js b/.vuepress/config.js index 22c0e01512..4866a04163 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -148,30 +148,63 @@ module.exports = { collapsable: false, children: [ { - title: 'Run in Production', - path: '/create/how_to/running_production', + title: 'Get Started', + collapsable: false, + children: [ + { + title: 'Install', + path: '/create/how_to/installation', + }, + { + title: 'Update', + path: '/create/how_to/updating', + }, + { + title: 'Run in Production', + path: '/create/how_to/running_production', + }, + ], }, { - title: 'Integrate into Your Documentation', - path: '/create/how_to/search_bar_for_docs', + title: 'Deploy', + collapsable: false, + children: [ + { + title: 'Deploy on DigitalOcean', + path: '/create/how_to/digitalocean_droplet', + }, + { + title: 'Deploy on AWS', + path: '/create/how_to/aws', + }, + { + title: 'Deploy on Qovery', + path: '/create/how_to/qovery' + }, + ], }, { - title: 'Deploy on DigitalOcean', - path: '/create/how_to/digitalocean_droplet', + title: 'Integrate', + collapsable: false, + children: [ + { + title: 'Add a Search Bar to Your Documentation', + path: '/create/how_to/search_bar_for_docs', + }, + { + title: 'Add to a React app', + path: '/create/how_to/meilisearch_react', + }, + ], }, { - title: 'Deploy on AWS', - path: '/create/how_to/aws', + title: 'Use HTTP/2 and SSL', + path: '/create/how_to/http2_ssl', }, - '/create/how_to/http2_ssl', { title: 'Use with Postman', path: '/create/how_to/postman_collection', }, - { - title: 'Add to a React app', - path: '/create/how_to/meilisearch_react', - }, ], }, { diff --git a/create/how_to/installation.md b/create/how_to/installation.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/create/how_to/updating.md b/create/how_to/updating.md new file mode 100644 index 0000000000..fecfa94c5d --- /dev/null +++ b/create/how_to/updating.md @@ -0,0 +1,107 @@ +# How to Update MeiliSearch + +MeiliSearch releases a new version every month. Every new release brings improvement: corrects bugs and/or adds new features. If you already have an instance of MeiliSearch running with some data you don’t want to lose, you are in the right place. We’ll guide you through the steps you need to take to have the latest version of MeiliSearch working with your good old data. + +MeiliSearch versions are not compatible with each other yet. If you try to use the same database with different versions, you’ll get the following error: + +`Error: Cannot open database, expected MeiliSearch engine version: 0.16.XX, current engine version: 0.18.1` + +If your actual version is v0.15.0 or above you just need to follow the next steps. If your version is v.14.0 or below, you can skip this part and go straight to link_to_part_2. + + +Upgrading from v.015.0 or above + + +It is very simple to upgrade from v.15.0 or above since the dumps feature is available for those versions. You just need to create a dump, which is sort of a copy of your dataset that can be used with any version of MeiliSearch. + +Step 1: Set all fields as displayedAttributes + +When creating dumps, MeiliSearch calls the same service as the GET /documents route. +Meaning that if a field is not in the displayed-attribute list, it won’t get returned with the document. + +By default, all fields are considered to be displayedAttributes. But, if you don’t want to lose document information, it is important to check that all fields are set to be displayed. You can verify your setup by making a GET request to the following endpoint: + +GET /indexes/:index_uid/settings/displayed-attributes + +If the returned value is: ["*"], you are good, +If not, then you need to reset the displayed-attributes settings to their default value ([*]). You can use the DELETE /indexes/:index_uid/settings/displayed-attributes endpoint. + + +Step 2: Create the dump + +To create a dump you just have to make a POST request to the following endpoint /dumps. +MeiliSearch will create a dumps/ folder to store the created dump. You can modify the dumps destination by specifying the route of the directory of your choice in the command line or through an environment variable, when starting the process. + +The server will then return a response that should like like this: + +{"uid":"20210212-151153878","status":"in_progress"} + +Since the dump creation is an asynchronous process, it may take some time. That’s why the uid comes in handy to know the process status. +You can make a GET /dumps/:dump_uid/status request. +And you’ll know if it’s still “in progress”, “done” or if some problem occurred. + + +Step 3: Import the dump + +Now that you’ve got your dump, you just need to install the latest version of MeiliSearch and import the dump at launch, like so: + +./meilisearch --import-dump /dumps/20210212-151153878.dump + +Importing a dump is the same process as indexing documents for the first time, it can require some time and memory. You may want to make batches to import your dumps. You can set the batch size through a CLI option: +--dump-batch-size +Or an environment variable: MEILI_DUMP_BATCH_SIZE +The default size iis 1024 documents per batch. + +Finally, don’t forget to set the displayedAttributes to their previous value, if needed. + + + + +Upgrading from v.014.0 or below + +Since dumps didn’t exist back then, the best solution would be to save your documents and your settings in JSON files. + +If you don’t have any particular setting you want to keep, you can move to step 2. + +Step 1: Save your settings + +First of all, we need to retrieve the settings using the GET /settings endpoint. It is important to first get the settings and then the documents because you might need to modify the settings to retrieve the documents in their entirety. You can get the settings and save them to a file using the method you prefer, for simplicity reasons, we are going to use curl in this example: + +curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/settings” -o mysettings.json + +Note: cURL can be instructed to save data into a local file, with the -o option (-o stands for output) + +Step 2: Check your settings + +In order to save all the information present in the documents. All fields must be set as displayedAttributes. + +You can verify your setup by making a GET request to the following endpoint: + +GET /indexes/:index_uid/settings/displayed-attributes + +If the returned value is: ["*"], all attributes are set as displayed, you can continue to step 3. + +If not, then you might want to reset the displayed-attributes settings to their default value (all). To do so, you just have to make a DELETE /settings/displayed-attributes request. + +Now that all fields are included in the displayedAttributes. You can proceed to save the documents, without risking any information loss. + +Step 3: Save the documents + +You can request your documents and save them in a file. An easy way to do so is using curl: + +curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/documents” -o mydocuments.json + + +Step 4: Upload your data to the latest version of MeiliSearch + +Finally, you can install the latest version of MeiliSearch and upload your data as usual. +If you saved your settings, the addition should be done in a particular order: +upload your settings +add your documents + +This order is crucial to indexation speed. + + + + + From 610bba34f0ea1d1fa52081a5e9b687d3b1fcca40 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Thu, 25 Feb 2021 09:40:09 -0500 Subject: [PATCH 02/16] Edit Qovery guide --- create/how_to/qovery.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/create/how_to/qovery.md b/create/how_to/qovery.md index 2d42a1d9cc..b369f43e35 100644 --- a/create/how_to/qovery.md +++ b/create/how_to/qovery.md @@ -1,4 +1,8 @@ -# How to deploy a MeiliSearch instance on Qovery +# Deploy a MeiliSearch Instance on Qovery + +_The following is a guest post by Romaric Philogène, CEO and Co-Founder of Qovery._ + +## Introduction In this tutorial I explain how to deploy a pre-configured Meilisearch instance in one click. @@ -6,10 +10,10 @@ In this tutorial I explain how to deploy a pre-configured Meilisearch instance i Deploying Meilisearch with Qovery provides: -* A pre-configured Meilisearch instance. -* A free SSD storage. -* A free SSL. -* Optional: custom domain. +- A pre-configured Meilisearch instance. +- A free SSD storage. +- A free SSL. +- Optional: custom domain. ## Step-by-step Meilisearch deployment @@ -19,16 +23,16 @@ Visit [the Qovery dashboard](https://start.qovery.com) to create an account if y ### 2. Create a project -* Click on the "create a project" button and give a name to your project. Eg. `Meilisearch` -* Click on "next". +- Click on the "create a project" button and give a name to your project, e.g. `MeiliSearch`. +- Click on "next". ### 3. Deploy Meilisearch ![meilisearch template](https://github.com/Qovery/public-resources/raw/master/screenshots/meilisearch-template.png) -* Click on the "use a template" button. -* Select "Meilisearch". -* Select your Github or Gitlab repository where Qovery will save your configuration files (Qovery uses Git as the source of truth). -* Click on "deploy". +- Click on the "use a template" button. +- Select "Meilisearch". +- Select your Github or Gitlab repository where Qovery will save your configuration files (Qovery uses Git as the source of truth). +- Click on "deploy". Congrats 🔥 - Your Meilisearch instance is deployed and ready to be used 🎉 From 161cac72b9bf1327f5f14f22f84fb3404ea644df Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Mon, 1 Mar 2021 15:49:21 -0500 Subject: [PATCH 03/16] Reduce visual clutter, improve README.md Set how to sidebarDepth to 0, organize sidebar categories, update README.md --- .vuepress/config.js | 26 ++++++++++++++++++-------- create/how_to/README.md | 20 ++++++++++++++------ 2 files changed, 32 insertions(+), 14 deletions(-) diff --git a/.vuepress/config.js b/.vuepress/config.js index 4866a04163..df888ca476 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -148,8 +148,9 @@ module.exports = { collapsable: false, children: [ { - title: 'Get Started', + title: 'Basics', collapsable: false, + sidebarDepth: 0, children: [ { title: 'Install', @@ -163,11 +164,16 @@ module.exports = { title: 'Run in Production', path: '/create/how_to/running_production', }, + { + title: 'Use with Postman', + path: '/create/how_to/postman_collection', + }, ], }, { title: 'Deploy', collapsable: false, + sidebarDepth: 0, children: [ { title: 'Deploy on DigitalOcean', @@ -186,9 +192,10 @@ module.exports = { { title: 'Integrate', collapsable: false, + sidebarDepth: 0, children: [ { - title: 'Add a Search Bar to Your Documentation', + title: 'Add a Search Bar to Your Docs', path: '/create/how_to/search_bar_for_docs', }, { @@ -198,12 +205,15 @@ module.exports = { ], }, { - title: 'Use HTTP/2 and SSL', - path: '/create/how_to/http2_ssl', - }, - { - title: 'Use with Postman', - path: '/create/how_to/postman_collection', + title: 'Miscellaneous', + collapsable: false, + sidebarDepth: 0, + children: [ + { + title: 'Use HTTP/2 and SSL', + path: '/create/how_to/http2_ssl', + }, + ], }, ], }, diff --git a/create/how_to/README.md b/create/how_to/README.md index 1113c9894c..a711930885 100644 --- a/create/how_to/README.md +++ b/create/how_to/README.md @@ -1,17 +1,25 @@ # 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. +These how-to guides take the reader through the steps required to solve a real-world problem. Like recipes in a cookbook, they are **repeatable solutions** you can return to anytime. 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/getting_started/quick_start.md). ## Table of Contents -How to: - +**Basics**: +- [Install MeiliSearch](/create/how_to/installation.md) +- [Update MeiliSearch](/create/how_to/updating.md) - [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) +- [Use Postman with MeiliSearch](/create/how_to/postman_collection.md) + +**Deploy**: - [Deploy MeiliSearch on DigitalOcean](/create/how_to/digitalocean_droplet.md) - [Deploy MeiliSearch on AWS](/create/how_to/aws.md) -- [Use HTTP/2 and SSL with MeiliSearch](/create/how_to/http2_ssl.md) -- [Use Postman with MeiliSearch](/create/how_to/postman_collection.md) +- [Deploy MeiliSearch on Qovery](/create/how_to/qovery.md) + +**Front-end Integration**: +- [Integrate a Relevant Search Bar to Your Documentation](/create/how_to/search_bar_for_docs.md) - [Implement Instant Search in Your React App in 5 Minutes](/create/how_to/meilisearch_react.md) + +**Miscellaneous**: +- [Use HTTP/2 and SSL with MeiliSearch](/create/how_to/http2_ssl.md) \ No newline at end of file From 7cd676950c07ca78efe85c8cd27fc16fbfcf2b5a Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Wed, 3 Mar 2021 10:16:24 -0500 Subject: [PATCH 04/16] Edit updating.md --- create/how_to/updating.md | 38 ++++++++++++++------------------------ 1 file changed, 14 insertions(+), 24 deletions(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index fecfa94c5d..0d24b65913 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -1,20 +1,20 @@ -# How to Update MeiliSearch +# Update to the Latest MeiliSearch Version -MeiliSearch releases a new version every month. Every new release brings improvement: corrects bugs and/or adds new features. If you already have an instance of MeiliSearch running with some data you don’t want to lose, you are in the right place. We’ll guide you through the steps you need to take to have the latest version of MeiliSearch working with your good old data. - -MeiliSearch versions are not compatible with each other yet. If you try to use the same database with different versions, you’ll get the following error: +Currently, MeiliSearch versions are not compatible with each other. If you try to use the same database with different versions, you’ll get the following error: `Error: Cannot open database, expected MeiliSearch engine version: 0.16.XX, current engine version: 0.18.1` -If your actual version is v0.15.0 or above you just need to follow the next steps. If your version is v.14.0 or below, you can skip this part and go straight to link_to_part_2. +If you already have a MeiliSearch database with some data you don’t want to lose, you are in the right place. We’ll guide you through all the steps to migrate your data to the most recent version of MeiliSearch. + +If your database version is v0.15.0 or above, continue to the next section. If your version is v.14.0 or below, [go here](#upgrading-from-v0140-or-below). -Upgrading from v.015.0 or above +## Upgrading from v.015.0 or above It is very simple to upgrade from v.15.0 or above since the dumps feature is available for those versions. You just need to create a dump, which is sort of a copy of your dataset that can be used with any version of MeiliSearch. -Step 1: Set all fields as displayedAttributes +### Step 1: Set all fields as displayedAttributes When creating dumps, MeiliSearch calls the same service as the GET /documents route. Meaning that if a field is not in the displayed-attribute list, it won’t get returned with the document. @@ -26,8 +26,7 @@ GET /indexes/:index_uid/settings/displayed-attributes If the returned value is: ["*"], you are good, If not, then you need to reset the displayed-attributes settings to their default value ([*]). You can use the DELETE /indexes/:index_uid/settings/displayed-attributes endpoint. - -Step 2: Create the dump +### Step 2: Create the dump To create a dump you just have to make a POST request to the following endpoint /dumps. MeiliSearch will create a dumps/ folder to store the created dump. You can modify the dumps destination by specifying the route of the directory of your choice in the command line or through an environment variable, when starting the process. @@ -40,8 +39,7 @@ Since the dump creation is an asynchronous process, it may take some time. That You can make a GET /dumps/:dump_uid/status request. And you’ll know if it’s still “in progress”, “done” or if some problem occurred. - -Step 3: Import the dump +### Step 3: Import the dump Now that you’ve got your dump, you just need to install the latest version of MeiliSearch and import the dump at launch, like so: @@ -54,16 +52,13 @@ The default size iis 1024 documents per batch. Finally, don’t forget to set the displayedAttributes to their previous value, if needed. - - - -Upgrading from v.014.0 or below +## Upgrading from v.014.0 or below Since dumps didn’t exist back then, the best solution would be to save your documents and your settings in JSON files. If you don’t have any particular setting you want to keep, you can move to step 2. -Step 1: Save your settings +### Step 1: Save your settings First of all, we need to retrieve the settings using the GET /settings endpoint. It is important to first get the settings and then the documents because you might need to modify the settings to retrieve the documents in their entirety. You can get the settings and save them to a file using the method you prefer, for simplicity reasons, we are going to use curl in this example: @@ -71,7 +66,7 @@ curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/settings” -o mysetting Note: cURL can be instructed to save data into a local file, with the -o option (-o stands for output) -Step 2: Check your settings +### Step 2: Check your settings In order to save all the information present in the documents. All fields must be set as displayedAttributes. @@ -85,14 +80,14 @@ If not, then you might want to reset the displayed-attributes settings to their Now that all fields are included in the displayedAttributes. You can proceed to save the documents, without risking any information loss. -Step 3: Save the documents +### Step 3: Save the documents You can request your documents and save them in a file. An easy way to do so is using curl: curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/documents” -o mydocuments.json -Step 4: Upload your data to the latest version of MeiliSearch +### Step 4: Upload your data to the latest version of MeiliSearch Finally, you can install the latest version of MeiliSearch and upload your data as usual. If you saved your settings, the addition should be done in a particular order: @@ -100,8 +95,3 @@ upload your settings add your documents This order is crucial to indexation speed. - - - - - From 70bb4712b4506acc44ab306e8cb89e8ba99bf4c7 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Sat, 6 Mar 2021 15:19:09 -0500 Subject: [PATCH 05/16] Revise updating guide, update installation page. --- .vuepress/config.js | 6 +- create/how_to/installation.md | 0 create/how_to/updating.md | 145 +++++++++++++++++-------- learn/getting_started/installation.md | 6 +- reference/features/field_properties.md | 2 +- 5 files changed, 101 insertions(+), 58 deletions(-) delete mode 100644 create/how_to/installation.md diff --git a/.vuepress/config.js b/.vuepress/config.js index df888ca476..a1d106086f 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -153,11 +153,7 @@ module.exports = { sidebarDepth: 0, children: [ { - title: 'Install', - path: '/create/how_to/installation', - }, - { - title: 'Update', + title: 'Update MeiliSearch', path: '/create/how_to/updating', }, { diff --git a/create/how_to/installation.md b/create/how_to/installation.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 0d24b65913..c978474c05 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -1,97 +1,146 @@ # Update to the Latest MeiliSearch Version -Currently, MeiliSearch versions are not compatible with each other. If you try to use the same database with different versions, you’ll get the following error: +Currently, MeiliSearch versions [are not compatible with each other](/learn/getting_started/installation.md#updating-meilisearch). The following guide will walk you through all the steps to migrate your database from an older version of MeiliSearch to the most recent one. -`Error: Cannot open database, expected MeiliSearch engine version: 0.16.XX, current engine version: 0.18.1` +If you already have a MeiliSearch database with some data you don’t want to lose, you are in the right place! -If you already have a MeiliSearch database with some data you don’t want to lose, you are in the right place. We’ll guide you through all the steps to migrate your data to the most recent version of MeiliSearch. +## Verify your database version -If your database version is v0.15.0 or above, continue to the next section. If your version is v.14.0 or below, [go here](#upgrading-from-v0140-or-below). +Before you can begin following this guide, you need to verify your database's **expected MeiliSearch version**, i.e. the version that indexed the data. You can do so by launching a MeiliSearch instance: +```bash +./meilisearch +``` -## Upgrading from v.015.0 or above +If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. Find and download the **expected version** [here](https://github.com/meilisearch/MeiliSearch/releases) before continuing. +If MeiliSearch launched successfully, simply use the [get version endpoint](/reference/api/version.md). -It is very simple to upgrade from v.15.0 or above since the dumps feature is available for those versions. You just need to create a dump, which is sort of a copy of your dataset that can be used with any version of MeiliSearch. + -### Step 1: Set all fields as displayedAttributes +Now that you know the version your database is using, proceed accordingly: -When creating dumps, MeiliSearch calls the same service as the GET /documents route. -Meaning that if a field is not in the displayed-attribute list, it won’t get returned with the document. +- **If your database version is v0.15.0 or above**, continue to the [next section](#updating-from-v0150-or-above). +- **If your version is v0.14.0 or below**, [go here](#updating-from-v0140-or-below). -By default, all fields are considered to be displayedAttributes. But, if you don’t want to lose document information, it is important to check that all fields are set to be displayed. You can verify your setup by making a GET request to the following endpoint: +## Updating from v0.15.0 or above -GET /indexes/:index_uid/settings/displayed-attributes +Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/features/dumps.md), updating is very simple. You just need to **create a dump** using the expected MeiliSearch version, then **import it** using the most recent one. -If the returned value is: ["*"], you are good, -If not, then you need to reset the displayed-attributes settings to their default value ([*]). You can use the DELETE /indexes/:index_uid/settings/displayed-attributes endpoint. +### Step 1: Set all fields as displayed attributes + +When creating dumps, MeiliSearch calls the same service as the [`GET /documents` route](/reference/api/documents.md#get-documents). This means that a field must be present in the [displayed-attributes list](/reference/features/field_properties.md#displayed-fields) in order to be saved in the dump. + +By default, all fields are included in `displayedAttributes`. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes](/reference/api/displayed_attributes.html#get-displayed-attributes) endpoint: + + + +If the returned value is `["*"]`, you can move on to the next step. + +If not, then you need to use the [reset displayed-attributes](/reference/api/displayed_attributes.html#reset-displayed-attributes) endpoint. + + ### Step 2: Create the dump -To create a dump you just have to make a POST request to the following endpoint /dumps. -MeiliSearch will create a dumps/ folder to store the created dump. You can modify the dumps destination by specifying the route of the directory of your choice in the command line or through an environment variable, when starting the process. +To create a dump, simply use the [create dump endpoint](/reference/api/dump.html#create-a-dump). -The server will then return a response that should like like this: + -{"uid":"20210212-151153878","status":"in_progress"} +MeiliSearch will store the dump in your dump directory, by default `dumps/`. You can [modify this directory](/reference/features/configuration.html#dumps-destination) through the command line or an environment variable. -Since the dump creation is an asynchronous process, it may take some time. That’s why the uid comes in handy to know the process status. -You can make a GET /dumps/:dump_uid/status request. -And you’ll know if it’s still “in progress”, “done” or if some problem occurred. +The server should return a response that looks like this: + +```json +{ + "uid": "20210212-151153878", + "status": "in_progress" +} +``` + +Since dump creation is an [asynchronous process](/learn/advanced/asynchronous_updates.md), you can use the returned `uid` to [track its status](/reference/api/dump.html#get-dump-status). + + + +This process can take some time. Once the status is `"done"`, move on to the next step. ### Step 3: Import the dump -Now that you’ve got your dump, you just need to install the latest version of MeiliSearch and import the dump at launch, like so: +Now that you’ve got your dump, you just need to [install the latest version of MeiliSearch](/learn/getting_started/installation.md#download-and-launch) and import the dump at launch, like so: + +```bash +# Install MeiliSearch in the local directory +curl -L https://install.meilisearch.com | sh -./meilisearch --import-dump /dumps/20210212-151153878.dump +# Launch MeiliSearch and import the specified dump file +./meilisearch --import-dump /dumps/name_of_your_dump.dump +``` -Importing a dump is the same process as indexing documents for the first time, it can require some time and memory. You may want to make batches to import your dumps. You can set the batch size through a CLI option: ---dump-batch-size -Or an environment variable: MEILI_DUMP_BATCH_SIZE -The default size iis 1024 documents per batch. +> Importing a dump is the same process as indexing documents. This can take some time and cause a spike in RAM usage. To save RAM, use a [smaller batch size](/reference/features/configuration.md#dump-batch-size). -Finally, don’t forget to set the displayedAttributes to their previous value, if needed. +Finally, don’t forget to set `displayedAttributes` back to its previous value, if necessary. -## Upgrading from v.014.0 or below +Congratulations! You have successfully migrated your MeiliSearch database to the latest version! 🎉 -Since dumps didn’t exist back then, the best solution would be to save your documents and your settings in JSON files. +## Updating from v0.14.0 or below -If you don’t have any particular setting you want to keep, you can move to step 2. +Since these versions predate the [dumps feature](/reference/features/dumps.md), the best solution is to export your documents and your [index settings](/reference/features/settings.md) as JSON files. + +If you don’t need to preserve index settings, skip directly to [step 2](#step-2-check-your-settings). ### Step 1: Save your settings -First of all, we need to retrieve the settings using the GET /settings endpoint. It is important to first get the settings and then the documents because you might need to modify the settings to retrieve the documents in their entirety. You can get the settings and save them to a file using the method you prefer, for simplicity reasons, we are going to use curl in this example: +First, use the [get settings](/reference/api/settings.md#get-settings) endpoint to retrieve the [settings](/reference/features/settings.md) of any indexes you want to preserve, and save them to a file using the method you prefer. -curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/settings” -o mysettings.json + -Note: cURL can be instructed to save data into a local file, with the -o option (-o stands for output) +For simplicity's sake, this example uses cURL. -### Step 2: Check your settings +```bash +# the -o option saves the output as a local file +curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/settings” -o mysettings.json +``` -In order to save all the information present in the documents. All fields must be set as displayedAttributes. +It is important to first export your settings before exporting documents, since retrieving the documents in their entirety may require modifying the settings. -You can verify your setup by making a GET request to the following endpoint: +### Step 2: Set all fields as displayed attributes -GET /indexes/:index_uid/settings/displayed-attributes +In order to retrieve all the fields present in your documents, all fields must be set as `displayedAttributes`. -If the returned value is: ["*"], all attributes are set as displayed, you can continue to step 3. +By default, all fields are included in `displayedAttributes`. Still, it's a good idea to verify your settings before continuing. Do so using the [get displayed attributes](/reference/api/displayed_attributes.html#get-displayed-attributes) endpoint: -If not, then you might want to reset the displayed-attributes settings to their default value (all). To do so, you just have to make a DELETE /settings/displayed-attributes request. + -Now that all fields are included in the displayedAttributes. You can proceed to save the documents, without risking any information loss. +If the returned value is `["*"]`, you can move on to the next step. -### Step 3: Save the documents +If not, use the [reset displayed-attributes](/reference/api/displayed_attributes.html#reset-displayed-attributes) endpoint. -You can request your documents and save them in a file. An easy way to do so is using curl: + -curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/documents” -o mydocuments.json +Now that all fields are **displayed**, you can proceed to save your documents without risking any information loss. + +### Step 3: Save your documents + +Use a GET request to retrieve your documents and save them using the method you prefer. + + +cURL provides an easy option for exporting the results of an API call: + +```bash +# the -o option saves the output as a local file +curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/documents” -o mydocuments.json +``` ### Step 4: Upload your data to the latest version of MeiliSearch -Finally, you can install the latest version of MeiliSearch and upload your data as usual. -If you saved your settings, the addition should be done in a particular order: -upload your settings -add your documents +Finally, [install the latest version of MeiliSearch](/learn/getting_started/installation.md) and upload your data as usual. + +If you chose to save your settings, make sure to follow this order: + +1. [Update your settings](/reference/api/settings.md#update-settings) +2. [Add your documents](/reference/api/documents.md#add-or-replace-documents) + +This order prevents double indexing and will save time and memory. -This order is crucial to indexation speed. +Congratulations! You have successfully migrated your MeiliSearch database to the latest version! 🎉 diff --git a/learn/getting_started/installation.md b/learn/getting_started/installation.md index 8e246c171a..39a3ea2879 100644 --- a/learn/getting_started/installation.md +++ b/learn/getting_started/installation.md @@ -130,9 +130,7 @@ Getting the latest version of MeiliSearch is a straightforward process: simply f 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](/learn/getting_started/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. +If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. To migrate your database to the most recent version of MeiliSearch, we recommend following our [dedicated guide](/create/how_to/updating.md). ### Migrating a Database to a Later Version @@ -140,4 +138,4 @@ Using [dumps](/reference/features/dumps.md), you can export your MeiliSearch dat 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**. -If you want a complete guide on how to update MeiliSearch on DigitalOcean, please [look at this GitHub issue](https://github.com/meilisearch/MeiliSearch/discussions/1187#discussioncomment-278125). +For a complete guide on how to migrate your database to the most recent version, [click here](/create/how_to/updating.md). \ No newline at end of file diff --git a/reference/features/field_properties.md b/reference/features/field_properties.md index 1ab27dba81..576aba61f7 100644 --- a/reference/features/field_properties.md +++ b/reference/features/field_properties.md @@ -16,7 +16,7 @@ When you perform a search, all searchable fields are searched for matching query Non-searchable fields are most useful for internal information that's not relevant to the search experience, such as URLs, sales numbers, or ratings used exclusively for sorting results. ::: tip -Even if you make a field non-searchable, it will remain stored in the database and can be made searchable again at a later time. +Even if you make a field non-searchable, it will remain [stored in the database](#data-storing) and can be made searchable again at a later time. ::: ### The Searchable Attributes List From 9e3904cbf332fe4b9be4d496a71aba307e87cc4e Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Sat, 6 Mar 2021 16:44:31 -0500 Subject: [PATCH 06/16] Improve installation.md --- create/how_to/updating.md | 2 +- learn/getting_started/installation.md | 41 ++++++++++++++++----------- reference/features/configuration.md | 4 +-- 3 files changed, 27 insertions(+), 20 deletions(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index c978474c05..054d4d672c 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -6,7 +6,7 @@ If you already have a MeiliSearch database with some data you don’t want to lo ## Verify your database version -Before you can begin following this guide, you need to verify your database's **expected MeiliSearch version**, i.e. the version that indexed the data. You can do so by launching a MeiliSearch instance: +Before we begin, you need to verify your database's **expected MeiliSearch version**, i.e. the version that indexed the data. You can do so by launching a MeiliSearch instance: ```bash ./meilisearch diff --git a/learn/getting_started/installation.md b/learn/getting_started/installation.md index 39a3ea2879..061a9ba91e 100644 --- a/learn/getting_started/installation.md +++ b/learn/getting_started/installation.md @@ -1,11 +1,11 @@ # Installation -## Download and launch +## Download and Launch :::: tabs ::: tab cURL -Download the **latest stable release** of MeiliSearch with **curl**. +Download the **latest stable release** of MeiliSearch with **cURL**. Launch MeiliSearch to start the server. @@ -96,21 +96,28 @@ cargo build --release :::: -After launching MeiliSearch, you should see the following response: +::: tip Compile for Best Performance +For best performance, compile MeiliSearch on the machine you intend to run it on. This way, the binary is optimized for your specific architecture. +::: -``` -888b d888 d8b 888 d8b .d8888b. 888 -8888b d8888 Y8P 888 Y8P d88P Y88b 888 -88888b.d88888 888 Y88b. 888 -888Y88888P888 .d88b. 888 888 888 "Y888b. .d88b. 8888b. 888d888 .d8888b 88888b. -888 Y888P 888 d8P Y8b 888 888 888 "Y88b. d8P Y8b "88b 888P" d88P" 888 "88b -888 Y8P 888 88888888 888 888 888 "888 88888888 .d888888 888 888 888 888 -888 " 888 Y8b. 888 888 888 Y88b d88P Y8b. 888 888 888 Y88b. 888 888 -888 888 "Y8888 888 888 888 "Y8888P" "Y8888 "Y888888 888 "Y8888P 888 888 - -Database path: "./data.ms" -Server listening on: "127.0.0.1:7700" -``` +::: details MeiliSearch on M1 Mac +At this time, MeiliSearch may not compile on M1 Macs. If you have issues installing MeiliSearch, please [create an issue](https://github.com/meilisearch/MeiliSearch/issues/new/choose) so we can improve our software! +::: + +::: details MeiliSearch on Windows +To install MeiliSearch on Windows, use Docker or compile from the source. + +A common compilation error (`"link.exe not found"`) can be solved by installing [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) (scroll down and click on **Tools for Visual Studio 2019**). + +MeiliSearch will allocate 100GB on launch. If disk space is an issue on your machine, adjust the [main database](/reference/features/configuration.md#max-mdb-size) and [update database](/reference/features/configuration.md#max-udb-size) maximums accordingly. +::: + +## Cloud Deploy + +To deploy MeiliSearch on a cloud service, follow one of our dedicated guides: +- [AWS](/create/how_to/aws.md) +- [DigitalOcean](/create/how_to/digitalocean_droplet.md) +- [Qovery](/create/how_to/qovery.md) ## Configuration Options @@ -128,7 +135,7 @@ Here is a list of [all the options and how to use them](/reference/features/conf Getting the latest version of MeiliSearch is a straightforward process: simply fetch and install the latest binary with your preferred method (see [installation](/learn/getting_started/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. +However, please note that prior to our official release (`v1.0`), all minor updates (`v0.X`) are considered breaking. In other words, **MeiliSearch databases are not compatible across versions** for as long as we are in beta. If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. To migrate your database to the most recent version of MeiliSearch, we recommend following our [dedicated guide](/create/how_to/updating.md). diff --git a/reference/features/configuration.md b/reference/features/configuration.md index f43fedda1c..e9e1ee9cf0 100644 --- a/reference/features/configuration.md +++ b/reference/features/configuration.md @@ -230,7 +230,7 @@ Depending on the OS, it is either the size that will be allocated on launch or t - On **UNIX** it is the maximum size. - 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. + Because this allocates 100GiB 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](/reference/under_the_hood/storage.md) @@ -254,7 +254,7 @@ Depending on the OS, it is either the size that will be allocated on launch or t - On **UNIX** it is the maximum size. - 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. + Because this allocates 100GiB 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](/reference/under_the_hood/storage.md) From 92292b35b555c937c2b18d749b4b524037e07465 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Sat, 6 Mar 2021 16:53:35 -0500 Subject: [PATCH 07/16] Fix link and style --- .vuepress/config.js | 2 +- create/how_to/README.md | 7 +++++-- create/how_to/updating.md | 26 +++++++++++++------------- learn/getting_started/installation.md | 3 ++- 4 files changed, 21 insertions(+), 17 deletions(-) diff --git a/.vuepress/config.js b/.vuepress/config.js index a1d106086f..5071e22939 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -181,7 +181,7 @@ module.exports = { }, { title: 'Deploy on Qovery', - path: '/create/how_to/qovery' + path: '/create/how_to/qovery', }, ], }, diff --git a/create/how_to/README.md b/create/how_to/README.md index a711930885..6f5e5e1c8a 100644 --- a/create/how_to/README.md +++ b/create/how_to/README.md @@ -7,19 +7,22 @@ This is not the section for tutorial content. If you'd like to follow a step-by- ## Table of Contents **Basics**: -- [Install MeiliSearch](/create/how_to/installation.md) + - [Update MeiliSearch](/create/how_to/updating.md) - [Run MeiliSearch in Production](/create/how_to/running_production.md) - [Use Postman with MeiliSearch](/create/how_to/postman_collection.md) **Deploy**: + - [Deploy MeiliSearch on DigitalOcean](/create/how_to/digitalocean_droplet.md) - [Deploy MeiliSearch on AWS](/create/how_to/aws.md) - [Deploy MeiliSearch on Qovery](/create/how_to/qovery.md) **Front-end Integration**: + - [Integrate a Relevant Search Bar to Your Documentation](/create/how_to/search_bar_for_docs.md) - [Implement Instant Search in Your React App in 5 Minutes](/create/how_to/meilisearch_react.md) **Miscellaneous**: -- [Use HTTP/2 and SSL with MeiliSearch](/create/how_to/http2_ssl.md) \ No newline at end of file + +- [Use HTTP/2 and SSL with MeiliSearch](/create/how_to/http2_ssl.md) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 054d4d672c..9f39e60050 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -1,6 +1,6 @@ # Update to the Latest MeiliSearch Version -Currently, MeiliSearch versions [are not compatible with each other](/learn/getting_started/installation.md#updating-meilisearch). The following guide will walk you through all the steps to migrate your database from an older version of MeiliSearch to the most recent one. +Currently, MeiliSearch versions [are not compatible with each other](/learn/getting_started/installation.md#updating-meilisearch). The following guide will walk you through all the steps to migrate your database from an older version of MeiliSearch to the most recent one. If you already have a MeiliSearch database with some data you don’t want to lose, you are in the right place! @@ -20,8 +20,8 @@ If MeiliSearch launched successfully, simply use the [get version endpoint](/ref Now that you know the version your database is using, proceed accordingly: -- **If your database version is v0.15.0 or above**, continue to the [next section](#updating-from-v0150-or-above). -- **If your version is v0.14.0 or below**, [go here](#updating-from-v0140-or-below). +- **If your database version is v0.15.0 or above**, continue to the [next section](#updating-from-v0-15-0-or-above). +- **If your version is v0.14.0 or below**, [go here](#updating-from-v0-14-0-or-below). ## Updating from v0.15.0 or above @@ -31,23 +31,23 @@ Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/fea When creating dumps, MeiliSearch calls the same service as the [`GET /documents` route](/reference/api/documents.md#get-documents). This means that a field must be present in the [displayed-attributes list](/reference/features/field_properties.md#displayed-fields) in order to be saved in the dump. -By default, all fields are included in `displayedAttributes`. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes](/reference/api/displayed_attributes.html#get-displayed-attributes) endpoint: +By default, all fields are included in `displayedAttributes`. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes](/reference/api/displayed_attributes.md#get-displayed-attributes) endpoint: If the returned value is `["*"]`, you can move on to the next step. -If not, then you need to use the [reset displayed-attributes](/reference/api/displayed_attributes.html#reset-displayed-attributes) endpoint. +If not, then you need to use the [reset displayed-attributes](/reference/api/displayed_attributes.md#reset-displayed-attributes) endpoint. ### Step 2: Create the dump -To create a dump, simply use the [create dump endpoint](/reference/api/dump.html#create-a-dump). +To create a dump, simply use the [create dump endpoint](/reference/api/dump.md#create-a-dump). -MeiliSearch will store the dump in your dump directory, by default `dumps/`. You can [modify this directory](/reference/features/configuration.html#dumps-destination) through the command line or an environment variable. +MeiliSearch will store the dump in your dump directory, by default `dumps/`. You can [modify this directory](/reference/features/configuration.md#dumps-destination) through the command line or an environment variable. The server should return a response that looks like this: @@ -58,7 +58,7 @@ The server should return a response that looks like this: } ``` -Since dump creation is an [asynchronous process](/learn/advanced/asynchronous_updates.md), you can use the returned `uid` to [track its status](/reference/api/dump.html#get-dump-status). +Since dump creation is an [asynchronous process](/learn/advanced/asynchronous_updates.md), you can use the returned `uid` to [track its status](/reference/api/dump.md#get-dump-status). @@ -84,9 +84,9 @@ Congratulations! You have successfully migrated your MeiliSearch database to the ## Updating from v0.14.0 or below -Since these versions predate the [dumps feature](/reference/features/dumps.md), the best solution is to export your documents and your [index settings](/reference/features/settings.md) as JSON files. +Since these versions predate the [dumps feature](/reference/features/dumps.md), the best solution is to export your documents and your [index settings](/reference/features/settings.md) as JSON files. -If you don’t need to preserve index settings, skip directly to [step 2](#step-2-check-your-settings). +If you don’t need to preserve index settings, skip directly to [step 2](#step-2-set-all-fields-as-displayed-attributes). ### Step 1: Save your settings @@ -105,15 +105,15 @@ It is important to first export your settings before exporting documents, since ### Step 2: Set all fields as displayed attributes -In order to retrieve all the fields present in your documents, all fields must be set as `displayedAttributes`. +In order to retrieve all the fields present in your documents, all fields must be set as `displayedAttributes`. -By default, all fields are included in `displayedAttributes`. Still, it's a good idea to verify your settings before continuing. Do so using the [get displayed attributes](/reference/api/displayed_attributes.html#get-displayed-attributes) endpoint: +By default, all fields are included in `displayedAttributes`. Still, it's a good idea to verify your settings before continuing. Do so using the [get displayed attributes](/reference/api/displayed_attributes.md#get-displayed-attributes) endpoint: If the returned value is `["*"]`, you can move on to the next step. -If not, use the [reset displayed-attributes](/reference/api/displayed_attributes.html#reset-displayed-attributes) endpoint. +If not, use the [reset displayed-attributes](/reference/api/displayed_attributes.md#reset-displayed-attributes) endpoint. diff --git a/learn/getting_started/installation.md b/learn/getting_started/installation.md index 061a9ba91e..94eac4a33f 100644 --- a/learn/getting_started/installation.md +++ b/learn/getting_started/installation.md @@ -115,6 +115,7 @@ MeiliSearch will allocate 100GB on launch. If disk space is an issue on your mac ## Cloud Deploy To deploy MeiliSearch on a cloud service, follow one of our dedicated guides: + - [AWS](/create/how_to/aws.md) - [DigitalOcean](/create/how_to/digitalocean_droplet.md) - [Qovery](/create/how_to/qovery.md) @@ -145,4 +146,4 @@ Using [dumps](/reference/features/dumps.md), you can export your MeiliSearch dat 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**. -For a complete guide on how to migrate your database to the most recent version, [click here](/create/how_to/updating.md). \ No newline at end of file +For a complete guide on how to migrate your database to the most recent version, [click here](/create/how_to/updating.md). From 00a94c898ba9319583ab524e760709486e24deb4 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Thu, 11 Mar 2021 11:34:12 -0500 Subject: [PATCH 08/16] Address feedback from bidoubiwa's review Improve guide on installing a specific MeiliSearch version; make explanation of dump directory clearer --- create/how_to/updating.md | 99 ++++++++++++++++++++++----- learn/getting_started/installation.md | 20 +++--- 2 files changed, 93 insertions(+), 26 deletions(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 9f39e60050..3fffb7913d 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -12,11 +12,72 @@ Before we begin, you need to verify your database's **expected MeiliSearch versi ./meilisearch ``` -If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. Find and download the **expected version** [here](https://github.com/meilisearch/MeiliSearch/releases) before continuing. +If MeiliSearch launches successfully, simply use the [get version endpoint](/reference/api/version.md) and [proceed to the next step](#proceed-according-to-your-database-version). -If MeiliSearch launched successfully, simply use the [get version endpoint](/reference/api/version.md). +```bash +curl -X GET “http://127.0.0.1:7700/version" +``` + +If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. You need to download the expected version and use that to launch your database. + +This step is different depending on which tool you used to download MeiliSearch. + +:::: tabs + +::: tab cURL +If you downloaded MeiliSearch using curl, find and download the **expected version** [here](https://github.com/meilisearch/MeiliSearch/releases) before continuing. +::: + +::: tab Homebrew + +```bash +brew install meilisearch@0.X.X +``` + +::: + +::: tab Source + +```bash +# Clone MeiliSearch and checkout the branch of the expected version +git clone https://github.com/meilisearch/MeiliSearch +cd MeiliSearch +git checkout v0.X.X + +# Update the rust toolchain to the latest version +rustup update + +# Compile the project +cargo build --release + +# Execute the server binary +./target/release/meilisearch +``` + +::: + +::: tab APT + +```bash +apt-get install meilisearch=0.X.X +``` + +::: + +::: tab Docker + +```bash +docker run -it --rm \ + -p 7700:7700 \ + -v $(pwd)/data.ms:/data.ms \ + getmeili/meilisearch:v0.X.X +``` - +::: + +:::: + +## Proceed according to your database version Now that you know the version your database is using, proceed accordingly: @@ -43,11 +104,22 @@ If not, then you need to use the [reset displayed-attributes](/reference/api/dis ### Step 2: Create the dump -To create a dump, simply use the [create dump endpoint](/reference/api/dump.md#create-a-dump). +Before creating your dump, verify that your [dump directory](/reference/features/configuration.md#dumps-destination) is somewhere accessible to you. By default this is a folder called `dumps` at the root of your MeiliSearch directory, but can be modified at launch. + +::: tip +If you're unsure where your MeiliSearch directory is located, try this: + +```bash +which meilisearch +``` + +::: - +To create a dump, simply use the [create dump endpoint](/reference/api/dump.md#create-a-dump). -MeiliSearch will store the dump in your dump directory, by default `dumps/`. You can [modify this directory](/reference/features/configuration.md#dumps-destination) through the command line or an environment variable. +```bash +curl -X POST "http://127.0.0.1:7700/dumps" +``` The server should return a response that looks like this: @@ -60,7 +132,9 @@ The server should return a response that looks like this: Since dump creation is an [asynchronous process](/learn/advanced/asynchronous_updates.md), you can use the returned `uid` to [track its status](/reference/api/dump.md#get-dump-status). - +```bash +curl -X GET "http://127.0.0.1:7700/dumps/:dump_uid/status" +``` This process can take some time. Once the status is `"done"`, move on to the next step. @@ -69,9 +143,6 @@ This process can take some time. Once the status is `"done"`, move on to the nex Now that you’ve got your dump, you just need to [install the latest version of MeiliSearch](/learn/getting_started/installation.md#download-and-launch) and import the dump at launch, like so: ```bash -# Install MeiliSearch in the local directory -curl -L https://install.meilisearch.com | sh - # Launch MeiliSearch and import the specified dump file ./meilisearch --import-dump /dumps/name_of_your_dump.dump ``` @@ -121,15 +192,11 @@ Now that all fields are **displayed**, you can proceed to save your documents wi ### Step 3: Save your documents -Use a GET request to retrieve your documents and save them using the method you prefer. - - - -cURL provides an easy option for exporting the results of an API call: +Use the [GET documents endpoint](/reference/api/documents.md#get-documents) to retrieve your documents and save them using the method you prefer. Make sure to set the limit parameter so that, if you have `n` documents, `limit ≥ n`. ```bash # the -o option saves the output as a local file -curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/documents” -o mydocuments.json +curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/documents?limit=n” -o mydocuments.json ``` ### Step 4: Upload your data to the latest version of MeiliSearch diff --git a/learn/getting_started/installation.md b/learn/getting_started/installation.md index 94eac4a33f..7a6dce1b7a 100644 --- a/learn/getting_started/installation.md +++ b/learn/getting_started/installation.md @@ -94,22 +94,22 @@ cargo build --release ::: -:::: +::: tab Windows +To install MeiliSearch on Windows, use Docker or compile from the source. -::: tip Compile for Best Performance -For best performance, compile MeiliSearch on the machine you intend to run it on. This way, the binary is optimized for your specific architecture. -::: +A common compilation error (`"link.exe not found"`) can be solved by installing [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) (scroll down and click on **Tools for Visual Studio 2019**). -::: details MeiliSearch on M1 Mac -At this time, MeiliSearch may not compile on M1 Macs. If you have issues installing MeiliSearch, please [create an issue](https://github.com/meilisearch/MeiliSearch/issues/new/choose) so we can improve our software! +MeiliSearch will allocate 100GB on launch. If disk space is an issue on your machine, adjust the [main database](/reference/features/configuration.md#max-mdb-size) and [update database](/reference/features/configuration.md#max-udb-size) maximums accordingly. ::: -::: details MeiliSearch on Windows -To install MeiliSearch on Windows, use Docker or compile from the source. +::: tab M1 Mac +At this time, MeiliSearch may not compile on M1 Macs. If you have problems installing MeiliSearch, please [create an issue](https://github.com/meilisearch/MeiliSearch/issues/new/choose) so we can improve our software! +::: -A common compilation error (`"link.exe not found"`) can be solved by installing [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) (scroll down and click on **Tools for Visual Studio 2019**). +:::: -MeiliSearch will allocate 100GB on launch. If disk space is an issue on your machine, adjust the [main database](/reference/features/configuration.md#max-mdb-size) and [update database](/reference/features/configuration.md#max-udb-size) maximums accordingly. +::: tip Compile for Best Performance +For best performance, compile MeiliSearch on the machine you intend to run it on. This way, the binary is optimized for your specific architecture. ::: ## Cloud Deploy From 0ab4cc4ee33152341c6614e8eae9632ddf1b95a4 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Thu, 11 Mar 2021 12:14:35 -0500 Subject: [PATCH 09/16] Add all curl examples Replace route descriptions with curl examples --- create/how_to/updating.md | 88 ++++++++++++++++++++++----------------- 1 file changed, 50 insertions(+), 38 deletions(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 3fffb7913d..31fd00ae31 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -12,15 +12,13 @@ Before we begin, you need to verify your database's **expected MeiliSearch versi ./meilisearch ``` -If MeiliSearch launches successfully, simply use the [get version endpoint](/reference/api/version.md) and [proceed to the next step](#proceed-according-to-your-database-version). +If MeiliSearch launches successfully, use the [get version endpoint](/reference/api/version.md) and [proceed to the next step](#proceed-according-to-your-database-version). ```bash -curl -X GET “http://127.0.0.1:7700/version" +curl -X GET 'http://127.0.0.1:7700/version' ``` -If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. You need to download the expected version and use that to launch your database. - -This step is different depending on which tool you used to download MeiliSearch. +If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, **your database is not compatible with the currently installed MeiliSearch version**. You need to download the expected version and use that instead. :::: tabs @@ -86,21 +84,27 @@ Now that you know the version your database is using, proceed accordingly: ## Updating from v0.15.0 or above -Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/features/dumps.md), updating is very simple. You just need to **create a dump** using the expected MeiliSearch version, then **import it** using the most recent one. +Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/features/dumps.md), updating is very simple. -### Step 1: Set all fields as displayed attributes +You just need to: +1. **Create a dump** using the *expected* MeiliSearch version. +2. **Import it** using the *most recent* MeiliSearch version. -When creating dumps, MeiliSearch calls the same service as the [`GET /documents` route](/reference/api/documents.md#get-documents). This means that a field must be present in the [displayed-attributes list](/reference/features/field_properties.md#displayed-fields) in order to be saved in the dump. +### Step 1: Set all fields as displayed attributes -By default, all fields are included in `displayedAttributes`. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes](/reference/api/displayed_attributes.md#get-displayed-attributes) endpoint: +When creating dumps, MeiliSearch calls the same method as the [GET documents endpoint](/reference/api/documents.md#get-documents). This means that a field must be present in the [displayed attributes list](/reference/features/field_properties.md#displayed-fields) in order to be included in the dump. - +By default, all fields are added to `displayedAttributes`. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes): -If the returned value is `["*"]`, you can move on to the next step. +```bash +curl -X GET 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +``` -If not, then you need to use the [reset displayed-attributes](/reference/api/displayed_attributes.md#reset-displayed-attributes) endpoint. +If the returned value is `["*"]`, you can move on to the [next step](#step-2-create-the-dump). If not, then you need to use the [reset displayed attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). - +```bash +curl -X DELETE 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +``` ### Step 2: Create the dump @@ -118,7 +122,7 @@ which meilisearch To create a dump, simply use the [create dump endpoint](/reference/api/dump.md#create-a-dump). ```bash -curl -X POST "http://127.0.0.1:7700/dumps" +curl -X POST 'http://127.0.0.1:7700/dumps' ``` The server should return a response that looks like this: @@ -133,7 +137,7 @@ The server should return a response that looks like this: Since dump creation is an [asynchronous process](/learn/advanced/asynchronous_updates.md), you can use the returned `uid` to [track its status](/reference/api/dump.md#get-dump-status). ```bash -curl -X GET "http://127.0.0.1:7700/dumps/:dump_uid/status" +curl -X GET 'http://127.0.0.1:7700/dumps/:dump_uid/status' ``` This process can take some time. Once the status is `"done"`, move on to the next step. @@ -144,10 +148,10 @@ Now that you’ve got your dump, you just need to [install the latest version of ```bash # Launch MeiliSearch and import the specified dump file -./meilisearch --import-dump /dumps/name_of_your_dump.dump +./meilisearch --import-dump /dumps/your_dump_file.dump ``` -> Importing a dump is the same process as indexing documents. This can take some time and cause a spike in RAM usage. To save RAM, use a [smaller batch size](/reference/features/configuration.md#dump-batch-size). +> Importing a dump is the same process as indexing documents. This can take time and cause a spike in RAM usage. To save RAM, use a [smaller batch size](/reference/features/configuration.md#dump-batch-size). Finally, don’t forget to set `displayedAttributes` back to its previous value, if necessary. @@ -155,48 +159,49 @@ Congratulations! You have successfully migrated your MeiliSearch database to the ## Updating from v0.14.0 or below -Since these versions predate the [dumps feature](/reference/features/dumps.md), the best solution is to export your documents and your [index settings](/reference/features/settings.md) as JSON files. +Since these versions predate the [dumps feature](/reference/features/dumps.md), the best solution is to export your documents and your [index settings](/reference/features/settings.md) as `.JSON` files. If you don’t need to preserve index settings, skip directly to [step 2](#step-2-set-all-fields-as-displayed-attributes). ### Step 1: Save your settings -First, use the [get settings](/reference/api/settings.md#get-settings) endpoint to retrieve the [settings](/reference/features/settings.md) of any indexes you want to preserve, and save them to a file using the method you prefer. - - - -For simplicity's sake, this example uses cURL. +First, use the [get settings endpoint](/reference/api/settings.md#get-settings) to retrieve the [settings](/reference/features/settings.md) of any indexes you want to preserve, and save them to a file using the method you prefer. ```bash # the -o option saves the output as a local file -curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/settings” -o mysettings.json +curl -X GET 'http://127.0.0.1:7700/indexes/:index_uid/settings' -o mysettings.json ``` -It is important to first export your settings before exporting documents, since retrieving the documents in their entirety may require modifying the settings. +Repeat this process for all indexes you wish to migrate. -### Step 2: Set all fields as displayed attributes +**It is important to save your settings before exporting documents**, since the next step may require you to modify the settings. -In order to retrieve all the fields present in your documents, all fields must be set as `displayedAttributes`. +### Step 2: Set all fields as displayed attributes -By default, all fields are included in `displayedAttributes`. Still, it's a good idea to verify your settings before continuing. Do so using the [get displayed attributes](/reference/api/displayed_attributes.md#get-displayed-attributes) endpoint: +To prevent data loss, all fields must be set as [displayed](/reference/features/field_properties.md#displayed-fields). - +By default, all fields are added to the displayed attributes list. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes): -If the returned value is `["*"]`, you can move on to the next step. +```bash +curl -X GET 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +``` -If not, use the [reset displayed-attributes](/reference/api/displayed_attributes.md#reset-displayed-attributes) endpoint. +If the returned value is `["*"]`, you can move on to the [next step](#step-2-create-the-dump). If not, then you need to use the [reset displayed-attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). - +```bash +curl -X DELETE 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +``` -Now that all fields are **displayed**, you can proceed to save your documents without risking any information loss. +Now that all fields are displayed, you can proceed to the next step. ### Step 3: Save your documents -Use the [GET documents endpoint](/reference/api/documents.md#get-documents) to retrieve your documents and save them using the method you prefer. Make sure to set the limit parameter so that, if you have `n` documents, `limit ≥ n`. +Use the [get documents endpoint](/reference/api/documents.md#get-documents) to retrieve your documents and save them using the method you prefer. Make sure to set the `limit` parameter so that, if you have `n` documents, `limit ≥ n`. Otherwise, you risk data loss. ```bash # the -o option saves the output as a local file -curl -X GET “http://127.0.0.1:7700/indexes/:index_uid/documents?limit=n” -o mydocuments.json +curl -X GET 'http://127.0.0.1:7700/indexes/:index_uid/documents?limit=n' \ + -o mydocuments.json ``` ### Step 4: Upload your data to the latest version of MeiliSearch @@ -205,9 +210,16 @@ Finally, [install the latest version of MeiliSearch](/learn/getting_started/inst If you chose to save your settings, make sure to follow this order: -1. [Update your settings](/reference/api/settings.md#update-settings) -2. [Add your documents](/reference/api/documents.md#add-or-replace-documents) +```bash +# Update your settings +curl -X POST -H "Content-Type: application/json" -d @mysettings.json \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings' + +# Then, add your documents +curl -X POST -H "Content-Type: application/json" -d @mydocuments.json \ + 'http://127.0.0.1:7700/indexes/:index_uid/documents' +``` -This order prevents double indexing and will save time and memory. +Since updating the settings requires re-indexing all documents, this order saves time and memory. Congratulations! You have successfully migrated your MeiliSearch database to the latest version! 🎉 From 26691069d32808c6d23f794506021744b6ac5f2c Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Thu, 11 Mar 2021 12:19:05 -0500 Subject: [PATCH 10/16] Make all code samples fit the window without scrolling --- create/how_to/updating.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 31fd00ae31..f8f2b19316 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -87,6 +87,7 @@ Now that you know the version your database is using, proceed accordingly: Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/features/dumps.md), updating is very simple. You just need to: + 1. **Create a dump** using the *expected* MeiliSearch version. 2. **Import it** using the *most recent* MeiliSearch version. @@ -97,13 +98,15 @@ When creating dumps, MeiliSearch calls the same method as the [GET documents end By default, all fields are added to `displayedAttributes`. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes): ```bash -curl -X GET 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +curl -X GET \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` If the returned value is `["*"]`, you can move on to the [next step](#step-2-create-the-dump). If not, then you need to use the [reset displayed attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). ```bash -curl -X DELETE 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +curl -X DELETE \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` ### Step 2: Create the dump @@ -169,7 +172,8 @@ First, use the [get settings endpoint](/reference/api/settings.md#get-settings) ```bash # the -o option saves the output as a local file -curl -X GET 'http://127.0.0.1:7700/indexes/:index_uid/settings' -o mysettings.json +curl -X GET \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings' -o mysettings.json ``` Repeat this process for all indexes you wish to migrate. @@ -183,13 +187,15 @@ To prevent data loss, all fields must be set as [displayed](/reference/features/ By default, all fields are added to the displayed attributes list. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes): ```bash -curl -X GET 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +curl -X GET \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` If the returned value is `["*"]`, you can move on to the [next step](#step-2-create-the-dump). If not, then you need to use the [reset displayed-attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). ```bash -curl -X DELETE 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' +curl -X DELETE \ + 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` Now that all fields are displayed, you can proceed to the next step. From 6ac6aeae048dc04ae918b925898dd431856a11c6 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Tue, 16 Mar 2021 18:22:28 -0400 Subject: [PATCH 11/16] Incorporate Fred's review Also rename Getting Started guide (quick_start.md) as Quick Start --- create/how_to/README.md | 4 +- create/how_to/updating.md | 147 ++++++++++++++++++++------ learn/getting_started/README.md | 2 +- learn/getting_started/installation.md | 18 +--- learn/getting_started/quick_start.md | 4 +- 5 files changed, 124 insertions(+), 51 deletions(-) diff --git a/create/how_to/README.md b/create/how_to/README.md index 6f5e5e1c8a..74d576773c 100644 --- a/create/how_to/README.md +++ b/create/how_to/README.md @@ -1,8 +1,8 @@ # 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 are **repeatable solutions** you can return to anytime. +Each guide in this section takes the reader through the steps required to solve a real-world problem. Like recipes in a cookbook, they are **repeatable solutions** you can return to many times. -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/getting_started/quick_start.md). +This is not the best section for MeiliSearch beginners. If you'd like to follow a step-by-step guide that introduces you to the basics of MeiliSearch, check out our [quick start guide](/learn/getting_started/quick_start.md). ## Table of Contents diff --git a/create/how_to/updating.md b/create/how_to/updating.md index f8f2b19316..78e9e646f5 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -1,33 +1,47 @@ # Update to the Latest MeiliSearch Version -Currently, MeiliSearch versions [are not compatible with each other](/learn/getting_started/installation.md#updating-meilisearch). The following guide will walk you through all the steps to migrate your database from an older version of MeiliSearch to the most recent one. +Currently, MeiliSearch databases can only be opened by the MeiliSearch version you used to create them. The following guide will walk you through all the steps to **migrate an existing database** from an older version of MeiliSearch to the most recent one. If you already have a MeiliSearch database with some data you don’t want to lose, you are in the right place! ## Verify your database version -Before we begin, you need to verify your database's **expected MeiliSearch version**, i.e. the version that indexed the data. You can do so by launching a MeiliSearch instance: +Before we begin, you need to **verify the version of MeiliSearch that's compatible with your database**, i.e. the version that indexed the data. You can do so by launching a MeiliSearch instance: ```bash ./meilisearch ``` -If MeiliSearch launches successfully, use the [get version endpoint](/reference/api/version.md) and [proceed to the next step](#proceed-according-to-your-database-version). +If MeiliSearch launches successfully, use the [get version endpoint](/reference/api/version.md), note your `pkgVersion`, and [proceed to the next step](#proceed-according-to-your-database-version). ```bash curl -X GET 'http://127.0.0.1:7700/version' ``` -If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, **your database is not compatible with the currently installed MeiliSearch version**. You need to download the expected version and use that instead. +The response should look something like this: + +```json +{ + "commitSha":"stringOfLettersAndNumbers", + "buildDate":"YYYY-MM-DDTimestamp", + "pkgVersion":"x.y.z" +} +``` + +If you get the error `Cannot open database, expected MeiliSearch engine version: 0.X.X, current engine version 0.Y.Y`, your database is not compatible with the currently installed MeiliSearch version. + +In this case, you need to **download the compatible version now** (i.e. `0.X.X` in the above error message) so that you can access and export your database. :::: tabs ::: tab cURL -If you downloaded MeiliSearch using curl, find and download the **expected version** [here](https://github.com/meilisearch/MeiliSearch/releases) before continuing. +If you downloaded MeiliSearch using `curl`, find and download the compatible version [here](https://github.com/meilisearch/MeiliSearch/releases) before continuing. ::: ::: tab Homebrew +Replace `0.X.X` with the version you would like to install. + ```bash brew install meilisearch@0.X.X ``` @@ -36,19 +50,21 @@ brew install meilisearch@0.X.X ::: tab Source +Replace `0.X.X` with the version you would like to install. + ```bash -# Clone MeiliSearch and checkout the branch of the expected version +# clone MeiliSearch and checkout the branch of the expected version git clone https://github.com/meilisearch/MeiliSearch cd MeiliSearch git checkout v0.X.X -# Update the rust toolchain to the latest version +# update the rust toolchain to the latest version rustup update -# Compile the project +# compile the project cargo build --release -# Execute the server binary +# execute the server binary ./target/release/meilisearch ``` @@ -56,6 +72,8 @@ cargo build --release ::: tab APT +Replace `0.X.X` with the version you would like to install. + ```bash apt-get install meilisearch=0.X.X ``` @@ -64,6 +82,8 @@ apt-get install meilisearch=0.X.X ::: tab Docker +Replace `0.X.X` with the version you would like to install. + ```bash docker run -it --rm \ -p 7700:7700 \ @@ -75,9 +95,9 @@ docker run -it --rm \ :::: -## Proceed according to your database version +### Proceed according to your database version -Now that you know the version your database is using, proceed accordingly: +Now that you know which MeiliSearch version your database is compatible with, proceed accordingly: - **If your database version is v0.15.0 or above**, continue to the [next section](#updating-from-v0-15-0-or-above). - **If your version is v0.14.0 or below**, [go here](#updating-from-v0-14-0-or-below). @@ -88,41 +108,81 @@ Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/fea You just need to: -1. **Create a dump** using the *expected* MeiliSearch version. -2. **Import it** using the *most recent* MeiliSearch version. +1. [Set all fields as displayed attributes](#step-1-set-all-fields-as-displayed-attributes) +2. [Create a dump using the MeiliSearch version that's compatible with your database](#step-2-create-the-dump) +3. [Import the dump using the most recent MeiliSearch version](#step-3-import-the-dump) ### Step 1: Set all fields as displayed attributes -When creating dumps, MeiliSearch calls the same method as the [GET documents endpoint](/reference/api/documents.md#get-documents). This means that a field must be present in the [displayed attributes list](/reference/features/field_properties.md#displayed-fields) in order to be included in the dump. +When creating dumps, MeiliSearch calls the same method as the [get documents endpoint](/reference/api/documents.md#get-documents). This means that all fields must be [displayed](/reference/features/field_properties.md#displayed-fields) in order to be saved in the dump. -By default, all fields are added to `displayedAttributes`. Still, it's a good idea to verify this before creating a dump. You can do so by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes): +Start by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes) to verify that **all attributes are displayed**. ```bash +# whenever you see :index_uid, replace it with your index's unique id curl -X GET \ 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` -If the returned value is `["*"]`, you can move on to the [next step](#step-2-create-the-dump). If not, then you need to use the [reset displayed attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). +If the response is `'displayedAttributes': '["*"]'`, you can move on to the [next step](#step-2-create-the-dump). + +If it's something else, then you need to use the [reset displayed attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards. ```bash curl -X DELETE \ 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` +This command should return an updateId: + +```json +{ + "updateId": 1 +} +``` + +Now that all fields are displayed, proceed to the next step. + ### Step 2: Create the dump -Before creating your dump, verify that your [dump directory](/reference/features/configuration.md#dumps-destination) is somewhere accessible to you. By default this is a folder called `dumps` at the root of your MeiliSearch directory, but can be modified at launch. +Before creating your dump, make sure that your [dump directory](/reference/features/configuration.md#dumps-destination) is somewhere accessible. By default, dumps are created in a folder called `dumps` at the root of your MeiliSearch directory. -::: tip If you're unsure where your MeiliSearch directory is located, try this: +:::: tabs + +::: tab OSX / Linux + ```bash which meilisearch ``` +The return should look like this: + +```bash +/absolute/path/to/your/meilisearch/directory +``` + ::: -To create a dump, simply use the [create dump endpoint](/reference/api/dump.md#create-a-dump). +::: tab Windows + +```bash +# if using PowerShell, replace where with where.exe +where meilisearch +``` + +The return should look like this: + +```bash +/absolute/path/to/your/meilisearch/directory +``` + +::: + +:::: + +To create a dump, use the [create dump endpoint](/reference/api/dump.md#create-a-dump). ```bash curl -X POST 'http://127.0.0.1:7700/dumps' @@ -137,26 +197,37 @@ The server should return a response that looks like this: } ``` -Since dump creation is an [asynchronous process](/learn/advanced/asynchronous_updates.md), you can use the returned `uid` to [track its status](/reference/api/dump.md#get-dump-status). +This process can take some time. Since dump creation is an [asynchronous process](/learn/advanced/asynchronous_updates.md), you can use the returned `uid` to [track its status](/reference/api/dump.md#get-dump-status). ```bash +# replace :dump_uid with the uid returned by the previous command curl -X GET 'http://127.0.0.1:7700/dumps/:dump_uid/status' ``` -This process can take some time. Once the status is `"done"`, move on to the next step. +Once the response to the previous command looks like this (`"status": "done"`), move on. + +```json +{ + "uid": "20210212-151153878", + "status": "done" +} +``` ### Step 3: Import the dump -Now that you’ve got your dump, you just need to [install the latest version of MeiliSearch](/learn/getting_started/installation.md#download-and-launch) and import the dump at launch, like so: +Now that you’ve got your dump, [install the latest version of MeiliSearch](/learn/getting_started/installation.md#download-and-launch) and [import the dump](/reference/features/dumps.md#importing-a-dump) at launch using the [CLI option](/reference/features/configuration.md#import-dump). ```bash -# Launch MeiliSearch and import the specified dump file +# install MeiliSearch +curl -L https://install.meilisearch.com | sh + +# launch MeiliSearch and import the specified dump file ./meilisearch --import-dump /dumps/your_dump_file.dump ``` -> Importing a dump is the same process as indexing documents. This can take time and cause a spike in RAM usage. To save RAM, use a [smaller batch size](/reference/features/configuration.md#dump-batch-size). +> Importing a dump is the same process as indexing documents. This can take time and cause a spike in memory usage; to save memory, use a [smaller batch size](/reference/features/configuration.md#dump-batch-size). -Finally, don’t forget to set `displayedAttributes` back to its previous value, if necessary. +Finally, don’t forget to set `displayedAttributes` back to its previous value if necessary. You can do this using the [update displayed attributes endpoint](/reference/api/displayed_attributes.md#update-displayed-attributes). Congratulations! You have successfully migrated your MeiliSearch database to the latest version! 🎉 @@ -164,7 +235,7 @@ Congratulations! You have successfully migrated your MeiliSearch database to the Since these versions predate the [dumps feature](/reference/features/dumps.md), the best solution is to export your documents and your [index settings](/reference/features/settings.md) as `.JSON` files. -If you don’t need to preserve index settings, skip directly to [step 2](#step-2-set-all-fields-as-displayed-attributes). +If you don’t need to preserve index settings, skip directly to [step two](#step-2-set-all-fields-as-displayed-attributes). ### Step 1: Save your settings @@ -191,22 +262,34 @@ curl -X GET \ 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` -If the returned value is `["*"]`, you can move on to the [next step](#step-2-create-the-dump). If not, then you need to use the [reset displayed-attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). +If the response is `'displayedAttributes': '["*"]'`, you can move on to the [next step](#step-2-create-the-dump). + +If it's something else, then you need to use the [reset displayed-attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards. ```bash curl -X DELETE \ 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` -Now that all fields are displayed, you can proceed to the next step. +This command should return an updateId: + +```json +{ + "updateId": 1 +} +``` + +Now that all fields are displayed, proceed to the next step. ### Step 3: Save your documents -Use the [get documents endpoint](/reference/api/documents.md#get-documents) to retrieve your documents and save them using the method you prefer. Make sure to set the `limit` parameter so that, if you have `n` documents, `limit ≥ n`. Otherwise, you risk data loss. +Use the [get documents endpoint](/reference/api/documents.md#get-documents) to retrieve your documents and save them using the method you prefer. Make sure to set the `limit` on documents returned so that, if you have some number of documents `n`, `limit ≥ n`. Otherwise, you risk data loss. ```bash # the -o option saves the output as a local file -curl -X GET 'http://127.0.0.1:7700/indexes/:index_uid/documents?limit=n' \ +# whenever you see :index_uid, replace it with your index's unique id +curl -X GET \ + 'http://127.0.0.1:7700/indexes/:index_uid/documents?limit=n' \ -o mydocuments.json ``` @@ -217,11 +300,11 @@ Finally, [install the latest version of MeiliSearch](/learn/getting_started/inst If you chose to save your settings, make sure to follow this order: ```bash -# Update your settings +# update your settings curl -X POST -H "Content-Type: application/json" -d @mysettings.json \ 'http://127.0.0.1:7700/indexes/:index_uid/settings' -# Then, add your documents +# then, add your documents curl -X POST -H "Content-Type: application/json" -d @mydocuments.json \ 'http://127.0.0.1:7700/indexes/:index_uid/documents' ``` diff --git a/learn/getting_started/README.md b/learn/getting_started/README.md index 56ffd259a7..c8a1adb499 100644 --- a/learn/getting_started/README.md +++ b/learn/getting_started/README.md @@ -7,7 +7,7 @@ It is **not** to provide exhaustive or universal instructions on how to use Meil ## Table of Contents: - [Installation](/learn/getting_started/installation.md) -- [Getting Started](/learn/getting_started/quick_start.md) +- [Quick Start Guide](/learn/getting_started/quick_start.md) - [Download and launch MeiliSearch](/learn/getting_started/quick_start.md#download-and-launch) - [Add documents](/learn/getting_started/quick_start.md#add-documents) - [Search!](/learn/getting_started/quick_start.md#search) diff --git a/learn/getting_started/installation.md b/learn/getting_started/installation.md index 7a6dce1b7a..1c82751847 100644 --- a/learn/getting_started/installation.md +++ b/learn/getting_started/installation.md @@ -102,10 +102,6 @@ A common compilation error (`"link.exe not found"`) can be solved by installing MeiliSearch will allocate 100GB on launch. If disk space is an issue on your machine, adjust the [main database](/reference/features/configuration.md#max-mdb-size) and [update database](/reference/features/configuration.md#max-udb-size) maximums accordingly. ::: -::: tab M1 Mac -At this time, MeiliSearch may not compile on M1 Macs. If you have problems installing MeiliSearch, please [create an issue](https://github.com/meilisearch/MeiliSearch/issues/new/choose) so we can improve our software! -::: - :::: ::: tip Compile for Best Performance @@ -134,16 +130,10 @@ Here is a list of [all the options and how to use them](/reference/features/conf ## 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](/learn/getting_started/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. In other words, **MeiliSearch databases are not compatible across versions** for as long as we are in beta. - -If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. To migrate your database to the most recent version of MeiliSearch, we recommend following our [dedicated guide](/create/how_to/updating.md). - -### Migrating a Database to a Later Version +Getting the latest version of MeiliSearch is a straightforward process: simply fetch and install the latest binary with your preferred method (see [Installation](/learn/getting_started/installation.md#download-and-launch) above). -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. +However, please note that **prior to our official release (`v1.0`), databases are not compatible across versions**. Any database created by MeiliSearch `v0.X` can only be read by that 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**. +### Migrating Your Database to a Later Version -For a complete guide on how to migrate your database to the most recent version, [click here](/create/how_to/updating.md). +If you get the error `Cannot open database, expected MeiliSearch engine version: X.X.X, current engine version Y.Y.Y`, your database is not compatible with the version you're using. To migrate your database to the most recent version of MeiliSearch, follow our [dedicated guide](/create/how_to/updating.md). diff --git a/learn/getting_started/quick_start.md b/learn/getting_started/quick_start.md index 47d588cd3d..9067762214 100644 --- a/learn/getting_started/quick_start.md +++ b/learn/getting_started/quick_start.md @@ -1,8 +1,8 @@ -# Getting Started +# Quick Start This quick tour will help you get started with MeiliSearch in only a few steps. -## Download and launch +## Download and Launch First of all, let's download and run MeiliSearch. From 55399e195e5a1f2b1bba0553e2c423c37699c4bb Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Tue, 16 Mar 2021 18:25:24 -0400 Subject: [PATCH 12/16] Wording --- create/how_to/updating.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 78e9e646f5..53ba12add8 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -124,7 +124,7 @@ curl -X GET \ 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` -If the response is `'displayedAttributes': '["*"]'`, you can move on to the [next step](#step-2-create-the-dump). +If the response is `{'displayedAttributes': '["*"]'}`, you can move on to the [next step](#step-2-create-the-dump). If it's something else, then you need to use the [reset displayed attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards. @@ -157,7 +157,7 @@ If you're unsure where your MeiliSearch directory is located, try this: which meilisearch ``` -The return should look like this: +It should return something like this: ```bash /absolute/path/to/your/meilisearch/directory @@ -172,7 +172,7 @@ The return should look like this: where meilisearch ``` -The return should look like this: +It should return something like this: ```bash /absolute/path/to/your/meilisearch/directory @@ -262,7 +262,7 @@ curl -X GET \ 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` -If the response is `'displayedAttributes': '["*"]'`, you can move on to the [next step](#step-2-create-the-dump). +If the response is `{'displayedAttributes': '["*"]'}`, you can move on to the [next step](#step-2-create-the-dump). If it's something else, then you need to use the [reset displayed-attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards. From c90b5facfeefa26be25ac378c87cee83f121bd98 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Tue, 16 Mar 2021 18:28:45 -0400 Subject: [PATCH 13/16] Fix style --- create/how_to/updating.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 53ba12add8..1986518073 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -114,7 +114,7 @@ You just need to: ### Step 1: Set all fields as displayed attributes -When creating dumps, MeiliSearch calls the same method as the [get documents endpoint](/reference/api/documents.md#get-documents). This means that all fields must be [displayed](/reference/features/field_properties.md#displayed-fields) in order to be saved in the dump. +When creating dumps, MeiliSearch calls the same method as the [get documents endpoint](/reference/api/documents.md#get-documents). This means that all fields must be [displayed](/reference/features/field_properties.md#displayed-fields) in order to be saved in the dump. Start by using the [get displayed attributes endpoint](/reference/api/displayed_attributes.md#get-displayed-attributes) to verify that **all attributes are displayed**. From 55701f091788df3aa2d9517a0b23b5b8b2818658 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Wed, 17 Mar 2021 14:29:25 -0400 Subject: [PATCH 14/16] Fix response to get displayed attributes --- create/how_to/updating.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 1986518073..b7f89e3f9f 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -262,7 +262,7 @@ curl -X GET \ 'http://127.0.0.1:7700/indexes/:index_uid/settings/displayed-attributes' ``` -If the response is `{'displayedAttributes': '["*"]'}`, you can move on to the [next step](#step-2-create-the-dump). +If the response is `'["*"]'`, you can move on to the [next step](#step-2-create-the-dump). If it's something else, then you need to use the [reset displayed-attributes endpoint](/reference/api/displayed_attributes.md#reset-displayed-attributes). Before doing this, make sure you save your list of displayed attributes somewhere so you can restore it afterwards. From da5f7805bb19d6129ab7379a682f4a92090ff3a8 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Wed, 17 Mar 2021 15:27:58 -0400 Subject: [PATCH 15/16] Small changes Change OSX to macOS, fix bug in Docker script, change wording --- create/how_to/updating.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index b7f89e3f9f..3bd1e2762f 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -87,7 +87,7 @@ Replace `0.X.X` with the version you would like to install. ```bash docker run -it --rm \ -p 7700:7700 \ - -v $(pwd)/data.ms:/data.ms \ + -v "$(pwd)/data.ms:/data.ms" \ getmeili/meilisearch:v0.X.X ``` @@ -104,9 +104,9 @@ Now that you know which MeiliSearch version your database is compatible with, pr ## Updating from v0.15.0 or above -Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/features/dumps.md), updating is very simple. +Because MeiliSearch v0.15.0 and above include the [dumps feature](/reference/features/dumps.md), updating is relatively simple. -You just need to: +In this guide, we will: 1. [Set all fields as displayed attributes](#step-1-set-all-fields-as-displayed-attributes) 2. [Create a dump using the MeiliSearch version that's compatible with your database](#step-2-create-the-dump) @@ -151,7 +151,7 @@ If you're unsure where your MeiliSearch directory is located, try this: :::: tabs -::: tab OSX / Linux +::: tab macOS / Linux ```bash which meilisearch From 6d2e9943804c51e197f9b1d2c9dc24c395effa16 Mon Sep 17 00:00:00 2001 From: Tommy <68053732+react-learner@users.noreply.github.com> Date: Wed, 17 Mar 2021 16:21:34 -0400 Subject: [PATCH 16/16] Update PowerShell version of which command Unable to verify this, hopefully someone with a PC can test --- create/how_to/updating.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/create/how_to/updating.md b/create/how_to/updating.md index 3bd1e2762f..ba54f4d2c9 100644 --- a/create/how_to/updating.md +++ b/create/how_to/updating.md @@ -165,10 +165,9 @@ It should return something like this: ::: -::: tab Windows +::: tab Windows CMD ```bash -# if using PowerShell, replace where with where.exe where meilisearch ``` @@ -180,6 +179,20 @@ It should return something like this: ::: +::: tab Windows PowerShell + +```bash +(Get-Command meilisearch).Path +``` + +It should return something like this: + +```bash +/absolute/path/to/your/meilisearch/directory +``` + +::: + :::: To create a dump, use the [create dump endpoint](/reference/api/dump.md#create-a-dump).