Join vignette - #6478

delete "next"

here there are ten rows which may be overly complex for a first demonstration example
could it be reduced to two rows?

That would be challenging, as I would need to modify the examples below, since they are related. However, I do not expect the user to pay much attention to that detail.

We can consider avoiding the table display.

it is ok to keep all ten rows if necessary, but smaller is better in terms of learning examples usually.

maybe use \ and _ instead of - ?

|
\__

secondary

primary instead of principal?

also where do these names, principal/secondary come from? I don't see them in ?data.table so I would suggest to keep the standard/docmented names, i and x

Toby, thanks for pointing this out, I will change it from principal to primary.

I am trying to keep using the documented reference.

I just thought it could be useful for a new user to understand that the i table is more important in defining the number of rows to return, regardless of whether they are trying to make a left or right join.

this is not true. In R you can pass any argument by name or position. on is 15th so it is difficult, but possible.

I understand your point.

Here is the new text

Please keep in mind that the standard argument order in data.table is dt[i, j, by]. For join operations, it is recommended to pass the on and nomatch arguments by name to avoid using j and by when they are not needed.

I'm not sure I understand "to avoid using j and by when they are not needed." can you please clarify?

Here is my attempt to clarify. Is this similar to what you meant? "For join operations using the data table square brackets, the first argument (i=table or names) is often specified as a positional argument, and the on and nomatch arguments are often specified by name, for example: dt1[dt2, on="variable", nomatch=0L]."

here is a demonstration that it is possible to use on argument by position instead of name (I don't think this is a great idea to do in practice though haha)

> dt1=data.table(x=1:2, y=3:4)
> dt2=data.table(x=2)
> dt1[dt2,,,,,,,,,,,,,,"x"]
       x     y
   <int> <int>
1:     2     4

change right to i ? or at least mention i in addition to right

I think "table in the square brackets" or "i argument" should be mentioned in addition to "table located on the right"

change right to i ? or at least mention i in addition to right

I think it can be confusing as the left join it's also an i join, just exchanging the position of each table

"id" quotes not necessary

four levels of section numbering (3.1.3.1) is difficult to understand. can it be kept to 2 or 3 please? (3.1) or (3.1.3)

please consider alternative whitespace formatting below.
when each argument of square brackets is on its own line, each argument can be commented easily

dt1 = ProductReceived[
  Products,
  on = c("product_id" = "id"),
  by = .EACHI,
  j = .(total_value_received  = sum(price * count))
]

I like this format.

temporal -> temporary

Add space after period (.)