Primary key guide

.code-samples.meilisearch.yaml

@@ -735,25 +735,32 @@ security_guide_delete_key_1: |-
   curl \
     -X DELETE 'http://localhost:7700/keys/d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4' \
     -H 'Authorization: Bearer masterKey'
-document_guide_create_index_primary_key: |-
+primary_field_guide_create_index_primary_key: |-
   curl \
     -X POST 'http://localhost:7700/indexes' \
     -H 'Content-Type: application/json' \
     --data-binary '{
-      "uid": "movies",
+      "uid": "books",
       "primaryKey": "reference_number"
     }'
-document_guide_add_document_primary_key: |-
+primary_field_guide_add_document_primary_key: |-
   curl \
-    -X POST 'http://localhost:7700/indexes/movies/documents?primaryKey=reference_number' \
+    -X POST 'http://localhost:7700/indexes/books/documents?primaryKey=reference_number' \
     -H 'Content-Type: application/json' \
     --data-binary '[{
         "reference_number": 287947,
-        "title": "Shazam",
-        "poster": "https://image.tmdb.org/t/p/w1280/xnopI5Xtky18MPhK40cZAGAOVeV.jpg",
-        "overview": "A boy is given the ability to become an adult superhero in times of need with a single magic word.",
-        "release_date": "2019-03-23"
+        "title": "Diary of a Wimpy Kid",
+        "author": "Jeff Kinney",
+        "genres": ["comedy","humor"],
+        "price": 5.00
      }]'
+primary_field_guide_update_primary_key: |
+  curl \
+    -X PUT 'http://localhost:7700/indexes/books' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+        "primaryKey" : "title"
+        }'
 tenant_token_guide_search_no_sdk_1: |-
   curl \
     -X POST 'http://127.0.0.1:7700/indexes/patient_medical_records/search' \

.vuepress/config.js

@@ -124,6 +124,7 @@ module.exports = {
             '/learn/core_concepts/documents',
             '/learn/core_concepts/indexes',
             '/learn/core_concepts/relevancy',
+            '/learn/core_concepts/primary_key',
           ],
         },
         {
@@ -343,7 +344,7 @@ module.exports = {
         pattern: '**/*.md',
         strictExt: true,
         ignoreFilePattern: ['errors', 'document_structure'],
-        ignoreHashPattern: ['actions-2'],
+        ignoreHashPattern: ['actions-2', 'primary-key-2'],
         exitLevel: 'warn',
       },
     ],

.vuepress/public/sample-template.yaml

@@ -119,8 +119,9 @@ security_guide_list_keys_1: |-
 security_guide_update_key_1: |-
 security_guide_delete_key_1: |-
 security_guide_search_key_1: |-
-document_guide_create_index_primary_key: |-
-document_guide_add_document_primary_key: |-
+primary_field_guide_create_index_primary_key: |-
+primary_field_guide_add_document_primary_key: |-
+primary_field_guide_update_primary_key: |-
 authentication_header_1: |-
 tenant_token_guide_search_no_sdk_1: |-
 tenant_token_guide_generate_sdk_1: |-

learn/core_concepts/documents.md

@@ -128,96 +128,9 @@ In the latter case, the field will be completely ignored when a search is perfor
 
 ## Primary field
 
-The primary field is a special field that must be present in all documents. Its attribute is the [primary key][primary-key] and its value is the [document id][document-id].
+The primary field is a special field that must be present in all documents. Its attribute is the [primary key](/learn/core_concepts/primary_key.md#primary-key-2) and its value is the [document id](/learn/core_concepts/primary_key.md#document-id).
 
-The primary field serves the important role of uniquely identifying each document stored in an index, ensuring that **it is impossible to have two exactly identical documents** present in the same index.
-
-Therefore, every document in the same index **must possess the exact same primary key** associated with a unique **document id** as value.
-
-#### Example:
-
-Suppose we have an index called `movie` that contains 200,000 documents. As shown below, each document is identified by a **primary field** containing the **primary key** `movie_id` and a **unique value** (the document id).
-
-Aside from the primary key, **documents in the same index are not required to share attributes**, e.g. you could have a document in this index without the "title" attribute.
-
-```json
-[
-  {
-    "movie_id": "1564saqw12ss",
-    "title": "Kung fu Panda",
-    "runtime": 95
-  },
-  {
-    "movie_id": "15k1j2kkw223s",
-    "title": "Batman Begins",
-    "gritty reboot": true
-  }
-]
-```
-
-### Primary key
-
-The primary key  is a **mandatory attribute linked to a unique value** the [document id][document-id]. It is part of the [primary field][primary-field].
-
-Each index recognizes **only one** primary key attribute. Once a primary key has been set for an index, it **cannot be changed anymore**. If no primary key is found in a document, **none of the documents will be stored.**
-
-#### Setting the primary key
-
-There are several ways to set the primary key for an index:
-
-- You can set it manually [on index creation](#setting-the-primary-key-on-index-creation)
-- You can set it manually [on document addition](#setting-the-primary-key-on-document-addition)
-- If no primary key is set, Meilisearch automatically [guesses the primary key](/learn/core_concepts/documents.md#meilisearch-guesses-your-primary-key) when you add documents
-
-#### Setting the primary key on index creation
-
-The code below creates an index called `movies` with `reference_number` as primary key:
-
-<CodeSamples id="document_guide_create_index_primary_key" />
-
-#### Setting the primary key on document addition
-
-The code below adds a document and sets `reference_number` as the index's primary key:
-
-<CodeSamples id="document_guide_add_document_primary_key" />
-
-#### Meilisearch guesses your primary key
-
-If the primary key has neither been set at index creation nor as a parameter of the add documents route, Meilisearch will search your first document for an attribute that contains the string `id` in a case-insensitive manner (e.g., `uid`, `MovieId`, `ID`, `123id123`) and set it as that index's primary key.
-
-If no corresponding attribute is found, the index will have no known primary key, and therefore, **no documents will be added**.
-
-#### Missing primary key error
-
-::: warning
-If you get the [`primary_key_inference_failed` error](/reference/api/error_codes.md#primary-key-inference-failed), the primary key was not recognized. This means **your primary key is wrongly formatted or absent**.
-:::
-
-Manually adding the primary key can be accomplished by using its name as a parameter for [the add document route](/reference/api/documents.md#add-or-replace-documents) or [the update index route](/reference/api/indexes.md#create-an-index).
-
-### Document Id
-
-The document id is the value associated to the primary key. It is part of the primary field, and acts as a unique identifier for each of the documents of a given index.
-
-This unique value ensures that two documents in the same index cannot be exactly alike. If two documents in the same index have the same id, then they are treated as the same document and the more recent one will replace the older.
-
-The document id must contain only `A-Z a-z 0-9` and `-_` characters.
-
-#### Example:
-
-Good:
-
-```json
-"id": "_Aabc012_"
-```
-
-Bad:
-
-```json
-"id": "@BI+* ^5h2%"
-```
-
-Take note that the document addition request in Meilisearch is atomic. This means that **if even a single document id is incorrectly formatted, an error will occur and none of your documents will be added**.
+To learn more, refer to the [primary key explanation](/learn/core_concepts/primary_key.md).
 
 ## Upload
 
@@ -238,7 +151,7 @@ When using the [route to add new documents](/reference/api/documents.md#add-or-u
 <CodeSamples id="documents_guide_add_movie_1" />
 
 [primary-field]: /learn/core_concepts/documents.md#primary-field
-[primary-key]: /learn/core_concepts/documents.md#primary-key
-[document-id]: /learn/core_concepts/documents.md#document-id
+[primary-key]: /learn/core_concepts/primary_key.md#primary-key-2
+[document-id]: /learn/core_concepts/primary_key.md#document-id
 [fields]: /learn/core_concepts/documents.md#fields
 [indexes]: /learn/core_concepts/indexes.md

learn/core_concepts/indexes.md

@@ -50,9 +50,9 @@ The `uid` is set at [index creation time](/reference/api/indexes.md#create-an-in
 
 An index is a collection of documents. All documents have a primary key, which is a mandatory field. This field is composed of a primary key attribute name and a unique value. All documents in a given index share the same primary key attribute but a different unique value.
 
-The primary key's attribute name **must** be known by the index. You can [set a primary key for an index or let it be inferred by Meilisearch](/learn/core_concepts/documents.md#setting-the-primary-key).
+The primary key's attribute name **must** be known by the index. You can [set a primary key for an index or let it be inferred by Meilisearch](/learn/core_concepts/primary_key.md#setting-the-primary-key).
 
-[Learn more about document primary key](/learn/core_concepts/documents.md#primary-key)
+[Learn more about document primary key](/learn/core_concepts/primary_key.md#primary-key-2)
 
 ## Relevancy rules