Documents
The /documents
route allows you to create, manage, and delete documents.
Get documents with POST
Get a set of documents.
Use offset
and limit
to browse through documents.
WARNING
filter
will not work without first explicitly adding attributes to the filterableAttributes
list. Learn more about filters in our dedicated guide.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
Name | Type | Default Value | Description |
---|---|---|---|
offset | Integer | 0 | Number of documents to skip |
limit | Integer | 20 | Number of documents to return |
fields | Array of strings/null | * | Document attributes to show (case-sensitive, comma-separated) |
filter | String/Array of array of strings/null | N/A | Refine results based on attributes in the filterableAttributes list |
NOTE
Sending an empty payload (--data-binary '{}'
) will return all documents in the index.
Response
Name | Type | Description |
---|---|---|
results | Array | An array of documents |
offset | Integer | Number of documents skipped |
limit | Integer | Number of documents returned |
total | Integer | Total number of documents in the index |
Example
curl \
-X POST http://localhost:7700/indexes/books/documents/fetch \
-H 'Content-Type: application/json' \
--data-binary '{
"filter": "(rating > 3 AND (genres = Adventure OR genres = Fiction)) AND language = English",
"fields": ["title", "genres", "rating", "language"],
"limit": 3
}'
Response: 200 Ok
{
"results":[
{
"title":"The Travels of Ibn Battuta",
"genres":[
"Travel",
"Adventure"
],
"language":"English",
"rating":4.5
},
{
"title":"Pride and Prejudice",
"genres":[
"Classics",
"Fiction",
"Romance",
"Literature"
],
"language":"English",
"rating":4
},
…
],
"offset":0,
"limit":3,
"total":5
}
Get documents with GET
DANGER
This endpoint will be deprecated in the near future. Consider using POST /indexes/{index_uid}/documents/fetch
instead.
Get a set of documents.
Using the query parameters offset
and limit
, you can browse through all your documents.filter
must be a string. To create filter expressions use AND
or OR
.
WARNING
filter
will not work without first explicitly adding attributes to the filterableAttributes
list. Learn more about filters in our dedicated guide.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Query parameters
Query Parameter | Default Value | Description |
---|---|---|
offset | 0 | Number of documents to skip |
limit | 20 | Number of documents to return |
fields | * | Document attributes to show (case-sensitive, comma-separated) |
filter | N/A | Refine results based on attributes in the filterableAttributes list |
Response
Name | Type | Description |
---|---|---|
results | Array | An array of documents |
offset | Integer | Number of documents skipped |
limit | Integer | Number of documents returned |
total | Integer | Total number of documents in the index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/documents?limit=2&filter=genres=action'
Response: 200 Ok
{
"results":[
{
"id": 364,
"title": "Batman Returns",
"overview": "While Batman deals with a deformed man calling himself the Penguin, an employee of a corrupt businessman transforms into the Catwoman.",
"genres": [
"Action",
"Fantasy"
],
"poster": "https://image.tmdb.org/t/p/w500/jKBjeXM7iBBV9UkUcOXx3m7FSHY.jpg",
"release_date": 708912000
},
{
"id": 13851,
"title":" Batman: Gotham Knight",
"overview": "A collection of key events mark Bruce Wayne's life as he journeys from beginner to Dark Knight.",
"genres": [
"Animation",
"Action",
"Adventure"
],
"poster": "https://image.tmdb.org/t/p/w500/f3xUrqo7yEiU0guk2Ua3Znqiw6S.jpg",
"release_date": 1215475200
}
],
"offset": 0,
"limit": 2,
"total": 5403
}
Get one document
Get one document using its unique id.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
document_id * | String/Integer | Document id of the requested document |
Query parameters
Query Parameter | Default Value | Description |
---|---|---|
fields | * | Document attributes to show (case-sensitive, comma-separated) |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/documents/25684?fields=id,title,poster,release_date'
Response: 200 Ok
{
"id": 25684,
"title": "American Ninja 5",
"poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
"release_date": "1993-01-01"
}
Add or replace documents
Add an array of documents or replace them if they already exist. If the provided index does not exist, it will be created.
If you send an already existing document (same document id) the whole existing document will be overwritten by the new document. Fields that are no longer present in the new document are removed. For a partial update of the document see the add or update documents endpoint.
This endpoint accepts the following content types:
application/json
application/x-ndjson
text/csv
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Query parameters
Query Parameter | Default Value | Description |
---|---|---|
primaryKey | null | Primary key of the index |
csvDelimiter | "," | Configure the character separating CSV fields. Must be a string containing one ASCII character. |
WARNING
Configuring csvDelimiter
and sending data with a content type other than CSV will cause Meilisearch to throw an error.
If you want to set the primary key of your index on document addition, it can only be done the first time you add documents to the index. After this, the primaryKey
parameter will be ignored if given.
Body
An array of documents. Each document is represented as a JSON object.
[
{
"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 \
-X POST 'http://localhost:7700/indexes/movies/documents' \
-H 'Content-Type: application/json' \
--data-binary '[
{
"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
{
"taskUid": 1,
"indexUid": "movies",
"status": "enqueued",
"type": "documentAdditionOrUpdate",
"enqueuedAt": "2021-08-11T09:25:53.000000Z"
}
You can use this taskUid
to get more details on the status of the task.
Add or update documents
Add a list of documents or update them if they already exist. If the provided index does not exist, it will be created.
If you send an already existing document (same document id) the old document will be only partially updated according to the fields of the new document. Thus, any fields not present in the new document are kept and remain unchanged.
To completely overwrite a document, check out the add or replace documents route.
If you want to set the primary key of your index through this route, you may only do so the first time you add documents to the index. If you try to set the primary key after having added documents to the index, the task will return an error.
This endpoint accepts the following content types:
application/json
application/x-ndjson
text/csv
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Query parameters
Query Parameter | Default Value | Description |
---|---|---|
primaryKey | null | Primary key of the documents |
csvDelimiter | "," | Configure the character separating CSV fields. Must be a string containing one ASCII character. |
WARNING
Configuring csvDelimiter
and sending data with a content type other than CSV will cause Meilisearch to throw an error.
Body
An array of documents. Each document is represented as a JSON object.
[
{
"id": 287947,
"title": "Shazam ⚡️"
}
]
Example
curl \
-X PUT 'http://localhost:7700/indexes/movies/documents' \
-H 'Content-Type: application/json' \
--data-binary '[
{
"id": 287947,
"title": "Shazam ⚡️",
"genres": "comedy"
}
]'
This document is an update of the document found in add or replace document.
The documents are matched because they have the same primary key value id: 287947
. This route will update the title
field as it changed from Shazam
to Shazam ⚡️
and add the new genres
field to that document. The rest of the document will remain unchanged.
Response: 202 Accepted
{
"taskUid": 1,
"indexUid": "movies",
"status": "enqueued",
"type": "documentAdditionOrUpdate",
"enqueuedAt": "2021-08-11T09:25:53.000000Z"
}
You can use this taskUid
to get more details on the status of the task.
Delete all documents
Delete all documents in the specified index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/documents'
Response: 202 Accepted
{
"taskUid": 1,
"indexUid": "movies",
"status": "enqueued",
"type": "documentDeletion",
"enqueuedAt": "2021-08-11T09:25:53.000000Z"
}
You can use this taskUid
to get more details on the status of the task.
Delete one document
Delete one document based on its unique id.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
document_id * | String/Integer | Document id of the requested document |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/documents/25684'
Response: 202 Accepted
{
"taskUid": 1,
"indexUid": "movies",
"status": "enqueued",
"type": "documentDeletion",
"enqueuedAt": "2021-08-11T09:25:53.000000Z"
}
You can use this taskUid
to get more details on the status of the task.
Delete documents by filter
Delete a set of documents based on a filter.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
A filter expression written as a string or array of array of strings for the documents to be deleted.
WARNING
filter
will not work without first explicitly adding attributes to the filterableAttributes
list. Learn more about filters in our dedicated guide.
"filter": "rating > 3.5"
WARNING
Sending an empty payload (--data-binary '{}'
) will return a bad_request
error.
Example
curl \
-X POST http://localhost:7700/indexes/movies/documents/delete \
-H 'Content-Type: application/json' \
--data-binary '{
"filter": "genres = action OR genres = adventure"
}'
Response: 202 Accepted
{
"taskUid": 1,
"indexUid": "movies",
"status": "enqueued",
"type": "documentDeletion",
"enqueuedAt": "2023-05-15T08:38:48.024551Z"
}
You can use this taskUid
to get more details on the status of the task.
Delete documents by batch
DANGER
This endpoint will be deprecated in the near future. Consider using POST /indexes/{index_uid}/documents/delete
instead .
Delete a set of documents based on an array of document ids.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
An array of numbers containing the unique ids of the documents to be deleted.
[23488, 153738, 437035, 363869]
Example
curl \
-X POST 'http://localhost:7700/indexes/movies/documents/delete-batch' \
-H 'Content-Type: application/json' \
--data-binary '[
23488,
153738,
437035,
363869
]'
Response: 202 Accepted
{
"taskUid": 1,
"indexUid": "movies",
"status": "enqueued",
"type": "documentDeletion",
"enqueuedAt": "2021-08-11T09:25:53.000000Z"
}
You can use this taskUid
to get more details on the status of the task.