Documents

Documents are objects composed of fields containing any data, a field is composed of an attribute and its associated data. This object form is used by most of the Meili API endpoints.

TIP

Documents identifiers are always converted into strings and only strings and integers are valid identifiers. It means that it is forbidden to use arrays or objects as identifier for example.

{
  "id": 3205,
  "title": "Interstellar",
  "description": "This is a great movie.",
  "type": ["sci fi", "space"]
}

In this document example, attributes are "id", "title", "description" and "type".
The fields are the combination of attributes and data (i.e. "title": "Interstellar").

Schemas

A schema is a representation of the documents attributes. It is used by Meili to know how to handle documents like which fields to display and which fields to index.

  • Indexed attributes are used by the search engine.
  • Displayed attributes will be shown when a document is returned.

TIP

By default the Meili dashboard infers the schema from the first document sent.

WARNING

Documents fields which do not correspond to the schema fields are ignored. The only mandatory document field is the identifier.

If you upload a file via the dashboard the schema is infered this way:

  • the order of the first document fields is the order of the schema fields
  • the identifier is the first field containing "id" (case insensitive)
  • every field is indexed and displayed

TIP

The order of the schema fields determines the precedence: a field which is declared before another one is more important.

{
  "id": ["identifier", "indexed", "displayed"],
  "title": ["indexed", "displayed"],
  "description": ["indexed", "displayed"],
  "type": ["indexed", "displayed"]
}

In this schema example we can see that every field is indexed and displayed. This is the typical schema that would be infered by uploading the previous document via the dashboard.

We can also deduct that the "id" attribute is more important than the "title", "description" and "type". Which means that if you search for something that matches in the "description" of the document A and in the "title" of the document B, the document B will be considered better than the document A. You can read more about these rules in the search section.

Get one document

GET
/indexes/:index/documents/:identifier

Get one document using its unique identifier.

Headers

Header Value
X-Meili-API-Key $API_KEY
Accept-encoding gzip, deflate

Path Variables

Variable Description
index The index UID
identifier The unique identifier of the document

Example

curl \
  --location \
  --request GET 'https://4eb345y7.getmeili.com/indexes/4eb345y7/documents/25684' \
  --header "X-Meili-API-Key: $API_KEY"

Response: 200 Ok

{
  "id": 25684,
  "title": "American Ninja 5",
  "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
  "overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.",
  "release_date": "1993-01-01"
}

Browse documents

GET
/indexes/:index/documents

Get the documents in an unordered way.

WARNING

This route is a non-optimized route, it can be a little bit slow to answer.

Headers

Header Value
X-Meili-API-Key $API_KEY
Content-Type application/json
Accept-encoding gzip, deflate

Path Variables

Variable Description
index The index UID

Query Parameters

Query Parameter Description Default Value
offset number of documents to skip 0
limit number of documents to take 20
attributesToRetrieve document attributes to show *

Example

curl \
  --location \
  --request GET 'https://4eb345y7.getmeili.com/indexes/4eb345y7/documents?limit=5' \
  --header "X-Meili-API-Key: $API_KEY"

Response: 200 Ok

[
  {
    "id": 25684,
    "release_date": "1993-01-01",
    "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg","title": "American Ninja 5",
    "overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja."
  },
  {
    "id": 468219,
    "title": "Dead in a Week (Or Your Money Back)",
    "release_date": "2018-09-12",
    "poster": "https://image.tmdb.org/t/p/w1280/f4ANVEuEaGy2oP5M0Y2P1dwxUNn.jpg",
    "overview": "William has failed to kill himself so many times that he outsources his suicide to aging assassin Leslie. But with the contract signed and death assured within a week (or his money back), William suddenly discovers reasons to live... However Leslie is under pressure from his boss to make sure the contract is completed."
  }
]

Add or Update documents

POST
/indexes/:index/documents

Insert a list of documents or update them if they already exist based on their unique identifiers.

The update id returned by this function can be sent to the get update status route to retrieve informations about its advancement.

Headers

Header Value
X-Meili-API-Key $API_KEY
Content-Type application/json
Accept-encoding gzip, deflate

Path Variables

Variable Description
index The index UID

Body

The body is composed of a Json array of documents composed of fields corresponding to the index schema. You can read more about fields and schemas.

WARNING

Documents fields which are not known to the index schema will be ignored

[
  {
    "id": 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"
  }
]

Example

curl \
  --location \
  --request POST 'https://4eb345y7.getmeili.com/indexes/4eb345y7/documents' \
  --header 'Content-Type: application/json' \
  --header "X-Meili-API-Key: $API_KEY" \
  --data '[{
      "id": 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"
    }]'

Response: 202 Accepted

{
  "updateId": 3
}

Batch write documents

POST
/indexes/:index/documents/batch

Insert and Delete multiple documents in one request.

The update id returned by this function can be sent to the get update status route to retrieve informations about its advancement.

Headers

Header Value
X-Meili-API-Key $API_KEY
Content-Type application/json
Accept-encoding gzip, deflate

Path Variables

Variable Description
index The index UID

Body

The body must contain a Json Object containing an insert and a delete field:

WARNING

Unknown documents attributes will be ignored. You can read more about that.

{
  "insert": [],
  "delete": []
}

Example

curl \
  --location \
  --request POST 'https://4eb345y7.getmeili.com/indexes/4eb345y7/documents' \
  --header 'Content-Type: application/json' \
  --header "X-Meili-API-Key: $API_KEY" \
  --data '{
      "insert": [
        {
          "id": 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"
        }
      ],
      "delete": [
        522681
      ]
    }'

Response: 202 Accepted

{
  "updateId": 12
}

Clear all documents

DELETE
/indexes/:index/documents

Delete all documents in the specified index.

The update id returned by this function can be sent to the get update status route to retrieve informations about its advancement.

Headers

Header Value
X-Meili-API-Key $API_KEY
Content-Type application/json

Path Variables

Variable Description
index The index UID

Example

curl \
  --location \
  --request DELETE 'https://4eb345y7.getmeili.com/indexes/4eb345y7/documents' \
  --header "X-Meili-API-Key: $API_KEY" \
  --header 'Content-Type: application/json'

Response: 202 Accepted

{
  "updateId": 37
}

Delete one document

DELETE
/indexes/:index/documents/:identifier

Delete one document based on its unique identifier.
You can read more about identifiers and schemas.

The update id returned by this function can be sent to the get update status route to retrieve informations about its advancement.

Headers

Header Value
X-Meili-API-Key $API_KEY

Path Variables

Variable Description
index The index UID

Example

  curl \
  --location \
  --request DELETE 'https://4eb345y7.getmeili.com/indexes/4eb345y7/documents/25684' \
  --header "X-Meili-API-Key: $API_KEY"

Response: 202 Accepted

{
  "updateId": 27
}

Delete multiple documents

POST
/indexes/:index/documents/delete

Delete a selection of documents based on array of identifiers.
You can read more about identifiers and schemas.

The update id returned by this function can be sent to the get update status route to retrieve informations about its advancement.

Headers

Header Value
X-Meili-API-Key $API_KEY
Content-Type application/json
Accept-encoding gzip, deflate

Path Variables

Variable Description
index The index UID

Body

The body must be a Json Array with the unique identifiers of the documents to delete.

[23488, 153738, 437035, 363869]

Example

  curl \
  --location \
  --request POST 'https://4eb345y7.getmeili.com/indexes/4eb345y7' \
  --header "X-Meili-API-Key: $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '[
      23488,
      153738,
      437035,
      363869
    ]'

Response: 202 Accepted

{
  "updateId": 127
}