Some types returned by task are not very clear

[bidoubiwa]

documentPartial

When using the route PUT /indexes/x/documents the type in the task is documentPartial. While I understand that it makes sense in a developer environment (more even in a Rust environment where it is used and thus accurate), I don't think it is very clear for others.
I understood it since I used it when doing some Rust, I'm not sure I would have understand it before.

Maybe something like: documentUpdate is more easy to understand.

clearAll

When using Delete /indexes/x/documents it returns clearAll. It does not give a lot of context. It could be about other things than documents

[curquiza]

I personally agree with these both points.

Following the @bidoubiwa's ideas, I suggest

• documentPartial-> documentUpdate
• clearAll -> allDocumentsDeletion (not sure about the s), since it only concerns the documents if I'm correct, not the settings.

WDYT people?

[curquiza]

documentDeletion is already used for the single document deletion and the batched document deletion. But you're right, we could also use it for this case. WDYT?

[bidoubiwa]

For clarity, maybe yours is better. It's easier to know what exactly happened. Both are good for me.

[gmourier]

We asked ourselves this question with @MarinPostma during the redesign of the tasks API.

In fact, documentAddition and documentPartial are both additions and updates.

documentAddition allows you to add documents and replace them.
documentPartial allows to add documents and merge a different representation.

What's is used in the industry to represent both an addition or an update is upsert. This is a contraction of update and insert that can be read as insert or update.

The problem with this is that there is no notion of merging or replacing concerning the update part. 🤔

We could use documentUpdate or documentUpsert to replace both documentAddition and documentPartial and use the details of a task to give information about how many documents were added, replaced, or partially updated for a task.

[bidoubiwa]

While upsert is technically correct, we would have the same initial issue that it is not clear. The word is not very common I think.

What about documentPartialUpdate ? In which case it makes sense for me.

I do prefer documentUpdate even if it is not nuanced enough. Also, I think it may be counter intuitive to use the method updateDocument and receive documentUpsert as task description, the user might not make the link.
As documentUpdate is widely used across the SDK's and did not raise any confusing issue by any user, it might tell us that they are not surprised by its behavior. same for addDocuments

[curquiza]

documentAdditionOrUpdate for both of them?

[curquiza]

Final decision then:

• documentPartial-> documentAdditionOrUpdate
• documentAddition-> documentAdditionOrUpdate
• clearAll -> documentDeletion

[curquiza]

@gmourier I let you update the spec 😇

[curquiza]

Maybe on this one since it seems to be linked into naming changes for the tasks resource: meilisearch/specifications#144

[gmourier]

Following the v0.28 release, this discussion is now locked.

We encourage you to create a new thread if needed.

Thank you ✨