Documents

The /documents route allows you to create, manage, and delete documents.

Learn more about documents.

Get documents

GET

/indexes/{index_uid}/documents

Get a set of documents.

Using the query parameters offset and limit, you can browse through all your documents.

NOTE

Documents are ordered by Meilisearch depending on the hash of their id.

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)

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'

client.index('movies').getDocuments({ limit: 2 })

client.index('movies').get_documents({'limit':2})

$client->index('movies')->getDocuments((new DocumentsQuery())->setLimit(2));

DocumentsQuery query = new DocumentsQuery().setLimit(2);
client.index("movies").getDocuments(query);

client.index('movies').documents(limit: 2)

var a []interface{}
client.Index("movies").GetDocuments(nil, &meilisearch.DocumentsQuery{
  Limit: 2,
}, &a)

await client.Index("movies").GetDocumentsAsync<Movie>(new DocumentsQuery() { Limit = 2 });

let index = client
  .index("movies");
let documents: DocumentsResults = DocumentsQuery::new(&index)
  .with_limit(2)
  .execute::<Movies>()
  .await
  .unwrap();

client.index("movies").getDocuments(params: DocumentsQuery(limit: 2)) { (result: Result<DocumentsResults<Movie>, Swift.Error>) in
    switch result {
    case .success(let movies):
        print(movies)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').getDocuments(params: DocumentsQuery(limit: 2));

Response: 200 Ok

{
  "results": [
    {
      "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."
    }
  ],
  "offset": 0,
  "limit": 2,
  "total": 500134
}

Get one document

GET

/indexes/{index_uid}/documents/{document_id}

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'

client
    .index('movies')
    .getDocument(25684, { fields: ['id', 'title', 'poster', 'release_date'] })

client.index('movies').get_document(25684, {
  'fields': ['id', 'title', 'poster', 'release_date']
})

$client->index('movies')->getDocument(25684, ['id', 'title', 'poster', 'release_date']);

DocumentQuery query = new DocumentQuery().setFields(new String[] {"id", "title", "poster", "release_date"});
client.index("movies").getDocument("25684", query);

client.index('movies').document(25684, fields: ['id', 'title', 'poster', 'release_date'])

var a interface{}
client.Index("movies").GetDocument("25684",&meilisearch.DocumentQuery{
  Fields: []string{"id", "title", "poster", "release_date"},
}, &a)

await client.Index("movies").GetDocumentAsync<Movie>(25684, new List<string> { "id", "title", "poster", "release_date" });

let index = client
  .index("movies");
let document = DocumentQuery::new(&index)
  .with_fields(["id", "title", "poster", "release_date"])
  .execute::<Movie>("25684")
  .await
  .unwrap();

client.index("movies").getDocument(25684) { (result: Result<Movie, Swift.Error>) in
    switch result {
    case .success(let movie):
        print(movie)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').getDocument(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

POST

/indexes/{index_uid}/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

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"
    }
  ]'

client.index('movies').addDocuments([{
    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'
}])

client.index('movies').add_documents([{
  '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'
}])

$client->index('movies')->addDocuments([
  [
    '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'
  ]
]);

client.index("movies").addDocuments("[{"
  + "\"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\""
  + "}]"
);

client.index('movies').add_documents([
  {
    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'
  }
])

documents := []map[string]interface{}{
  {
    "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",
  },
}
client.Index("movies").AddDocuments(documents)

var movie = new[]
{
    new Movie
    {
          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.",
          ReleaseDate = "2019-03-23"
    }
};
await index.AddDocumentsAsync(movie);

let task: TaskInfo = client
  .index("movies")
  .add_or_replace(&[
    Movie {
      id: 287947,
      title: "Shazam".to_string(),
      poster: "https://image.tmdb.org/t/p/w1280/xnopI5Xtky18MPhK40cZAGAOVeV.jpg".to_string(),
      overview: "A boy is given the ability to become an adult superhero in times of need with a single magic word.".to_string(),
      release_date: "2019-03-23".to_string(),
    }
  ], None)
  .await
  .unwrap();

let documentJsonString = """
[
  {
    "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"
  }
]
"""
let documents: Data = documentJsonString.data(using: .utf8)!

client.index("movies").addDocuments(documents: documents) { (result) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').addDocuments([
  {
    '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

PUT

/indexes/{index_uid}/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

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"
    }
  ]'

client.index('movies').updateDocuments([{
    id: 287947,
    title: 'Shazam ⚡️',
    genres: 'comedy'
}])

client.index('movies').update_documents([{
    'id': 287947,
    'title': 'Shazam ⚡️',
    'genres': 'comedy'
}])

$client->index('movies')->updateDocuments([
  [
    'id' => 287947,
    'title' => 'Shazam ⚡️',
    'genres' => 'comedy'
  ]
]);

client.index("movies").updateDocuments("[{
  + "\"id\": 287947,"
  + "\"title\": \"Shazam ⚡️\","
  + "\"genres\": \"comedy\""
  + "}]"
);

client.index('movies').update_documents([
  {
    id: 287947,
    title: 'Shazam ⚡️',
    genres: 'comedy'
  }
])

documents := []map[string]interface{}{
  {
    "id":     287947,
    "title":  "Shazam ⚡️",
    "genres": "comedy",
  },
}
client.Index("movies").UpdateDocuments(documents)

var movie = new[]
{
    new Movie { Id = "287947", Title = "Shazam ⚡️", Genres = "comedy" }
};
await index.UpdateDocumentsAsync(movie);

// Define the type of our documents
#[derive(Serialize, Deserialize)]
struct IncompleteMovie {
  id: usize,
  title: String
}

let task: TaskInfo = client
  .index("movies")
  .add_or_update(&[
    IncompleteMovie {
      id: 287947,
      title: "Shazam ⚡️".to_string()
    }
  ], None)
  .await
  .unwrap();

let documentJsonString = """
[
  {
    "reference_number": 287947,
    "title": "Shazam ⚡️",
    "genres": "comedy"
  }
]
"""
let documents: Data = documentJsonString.data(using: .utf8)!

client.index("movies").updateDocuments(documents: documents) { (result) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').updateDocuments([
  {
    '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

/indexes/{index_uid}/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'

client.index('movies').deleteAllDocuments()

client.index('movies').delete_all_documents()

$client->index('movies')->deleteAllDocuments();

client.index("movies").deleteAllDocuments();

client.index('movies').delete_all_documents

client.Index("movies").DeleteAllDocuments()

await client.Index("movies").DeleteAllDocumentsAsync();

let task: TaskInfo = client
  .index("movies")
  .delete_all_documents()
  .await
  .unwrap();

client.index("movies").deleteAllDocuments() { (result) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').deleteAllDocuments();

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

/indexes/{index_uid}/documents/{document_id}

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'

client.index('movies').deleteDocument(25684)

client.index('movies').delete_document(25684)

$client->index('movies')->deleteDocument(25684);

client.index("movies").deleteDocument("25684");

client.index('movies').delete_document(25684)

client.Index("movies").DeleteDocument("25684")

await client.Index("movies").DeleteOneDocumentAsync("25684");

let task: TaskInfo = client
  .index("movies")
  .delete_document(25684)
  .await
  .unwrap();

client.index("movies").deleteDocument("25684") { (result) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').deleteDocument(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 batch

POST

/indexes/{index_uid}/documents/delete-batch

Delete a selection of documents based on an array of document id's.

Path parameters

Name	Type	Description
index_uid *	String	uid of the requested index

Body

An array of numbers containing the unique id's 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
  ]'

client.index('movies').deleteDocuments([23488, 153738, 437035, 363869])

client.index('movies').delete_documents([23488, 153738, 437035, 363869])

$client->index('movies')->deleteDocuments([23488, 153738, 437035, 363869]);

client.index("movies").deleteDocuments(Arrays.asList(new String[]
{
  "23488",
  "153738",
  "437035",
  "363869"
}));

client.index('movies').delete_documents([23488, 153738, 437035, 363869])

client.Index("movies").DeleteDocuments([]string{
  "23488",
  "153738",
  "437035",
  "363869",
})

await client.Index("movies").DeleteDocumentsAsync(new[] { "23488", "153738", "437035", "363869" });

let task: TaskInfo = client
  .index("movies")
  .delete_documents(&[23488, 153738, 437035, 363869])
  .await
  .unwrap();

client.index("movies").deleteBatchDocuments(["23488", "153738", "437035", "363869"]) {
(result) in
      switch result {
      case .success(let task):
          print(task)
      case .failure(let error):
          print(error)
      }
  }

await client.index('movies').deleteDocuments([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.