Follow up DOC-215 / Updated lead paragraph

[nerpaula]

Follow up on DOC-215. Updated lead paragraph to avoid ambiguity.

[romanatarango]

lgtm

[Simran-B]

Discussion from #1181:

Simran-B:

This is getting out of hand... The part about system attributes was merely a side note, and it's mentioned five times on the page now. I don't see a need to mention it in the lead paragraph, too, which is only meant as a synopsis that can be inaccurate for the sake of providing a general overview. It's also incorrect to say that non-system attributes are excluded (_from and _to are system attributes but can be modified for a long time).

---

romanatarango:

I see no harm in repeating the same information to avoid that the user misunderstands it. This is not a poem, it doesn't need to be nice, it has to be unambiguous. Not every user reads the whole page every time she needs to recall something, I guess most people never read the whole page. I want to avoid that a user reads the synopsis ("replace documents with all their attributes"), tries to replace all the attributes (how many people would check further?), this doesn't work, the user searches for a bug in her code for hours, asks the support - just to learn that the sentence in the synopsis is inaccurate.

My suggestion does not say that system (you mean system, not non-system) attributes are excluded, it says that non-system attributes are replaced. It doesn't say anything about system attributes at all (a simplification for the synopsis but nothing incorrect).

---

Simran-B:

I meant to write:

It's incorrect to say that system attributes are excluded

"It replaces documents with all their non-system attributes" or "It replaces documents with all their attributes excluding system attributes" is the same statement. Depending on the definition of system attributes,

• every attribute that starts with an underscore is a system attribute
• only top-level attributes that start with an underscore are system attributes
• only specific attributes are system attributes, namely _key, _id, _rev, _from, and _to, for which there is a special treatment in code and the API
• only specific attributes are system attributes, namely _key, _id, and _rev, which are immutable (_key), virtual attributes (_id), or not user-controlled (_rev).

This is not properly defined, and you can find inconsistent behavior concerning system attributes in ArangoDB. If you don't expect users to read more than the subheading, then we need to clearly state in the synopsis what it does and doesn't replace. It does replace _from and _to (if provided by the user). It does not replace the other three, but that is not directly related to the AQL UPDATE and REPLACE operations but a general property of the data model and system.

---

romanatarango:

The statements, indeed, mean the same. But these are no statements about system attributes. They speak about non-system attributes.

I agree, it should be more clarity about what system collections are, may be worth a ticket.

[Simran-B]

Well, there are different ways it could be interpreted

You can use REPLACE operations to completely replace documents with all their non-system attributes in a collection

It could either mean that you can replace attributes but not system attributes (including _from and _to) or that you can replace non-system attributes and that no statement is supposed to be made about system attributes. It's ambiguous.

I'm not sure how we would define what system attributes really are as long as the server shows different behavior. For example, you cannot index sub(!)-attributes called _id, even though the true system attribute is only the top-level _id attribute. This makes no sense from a user perspective (but has technical or rather effort reasons).

Regarding the edge attributes, they were true system attributes originally but behave as normal user attributes nowadays in terms of modifying their values, etc. However, they are still special, and they follow the naming conventions for system attributes. Are they system attributes or not?

[romanatarango]

Well, there are different ways it could be interpreted

You can use REPLACE operations to completely replace documents with all their non-system attributes in a collection

It could either mean that you can replace attributes but not system attributes (including _from and _to) or that you can replace non-system attributes and that no statement is supposed to be made about system attributes. It's ambiguous.

Well, it shouldn't be interpreted in the first sense, but you are right, it can. What about:
You can use REPLACE operation to completely replace documents with all their non-system and some system attributes in a collection?

Still short, correct, no ambiguity, details are below. (Btw, "operation", not "operations".)

I'm not sure how we would define what system attributes really are as long as the server shows different behavior. For example, you cannot index sub(!)-attributes called _id, even though the true system attribute is only the top-level _id attribute. This makes no sense from a user perspective (but has technical or rather effort reasons).

Regarding the edge attributes, they were true system attributes originally but behave as normal user attributes nowadays in terms of modifying their values, etc. However, they are still special, and they follow the naming conventions for system attributes. Are they system attributes or not?

In an ideal world, one would define system attributes (in some sense) and all other important groups of attributes. And use them consistently, preferably with links to the definitions. What is called "system" and what, say, "semi-system" would be a matter of taste. Quite some work, though.